头文件中的算法接口：排序、查找等算法的通用接口设计

各位同学，今天我们来聊一个很实在的话题——头文件里的算法接口该怎么设计。

说实话，我见过太多项目里，排序、查找这些基础算法被写得五花八门。有的用全局数组，有的硬编码比较函数，有的甚至把算法实现直接塞进头文件里。嗯，每次看到这种代码，我都忍不住想：这要是换个数据类型，是不是得重写一遍？

所以今天，我就把自己这些年总结的一套通用算法接口设计思路，拿出来跟大家分享。

为什么需要通用接口？

你想想看，排序算法本身跟数据类型是无关的。冒泡排序、快速排序，它们只关心「怎么比大小」和「怎么交换元素」。至于你排的是int、float还是结构体，算法本身并不在乎。

我在项目中遇到过这样一个场景：一个嵌入式设备需要同时排序温度传感器数据（float数组）和报警优先级（结构体数组）。如果每个类型都写一套排序函数，那代码量直接翻倍，而且维护起来特别痛苦。

所以，通用接口的核心思想就是：把算法逻辑与数据类型解耦。

通用排序接口设计

我们先看一个经典的排序接口。我习惯用C标准库的qsort作为参考模板，因为它已经被无数项目验证过了。

/* sort.h - 通用排序接口 */
#ifndef SORT_H
#define SORT_H

#include <stddef.h>

/* 比较函数指针类型 */
typedef int (*cmp_func_t)(const void *a, const void *b);

/* 通用排序函数 */
void sort_generic(void *base, size_t nmemb, size_t size, cmp_func_t cmp);

/* 常用比较函数（可选） */
int cmp_int(const void *a, const void *b);
int cmp_float(const void *a, const void *b);
int cmp_str(const void *a, const void *b);

#endif /* SORT_H */

这里的关键点有三个：

• void *base：指向待排序数组的起始地址，不关心具体类型
• size_t nmemb：元素个数
• size_t size：每个元素的大小（字节数）
• cmp_func_t cmp：比较函数的指针，由调用者提供

说白了，你只要告诉排序函数「数据在哪、有多少、每个多大、怎么比」，它就能帮你排好序。

通用查找接口设计

查找接口的设计思路跟排序类似。我们来看一个二分查找的通用接口：

/* search.h - 通用查找接口 */
#ifndef SEARCH_H
#define SEARCH_H

#include <stddef.h>

/* 查找结果结构体 */
typedef struct {
    void *data;      /* 找到的元素指针，未找到为NULL */
    size_t index;    /* 元素在数组中的索引 */
    int found;       /* 是否找到：1找到，0未找到 */
} search_result_t;

/* 通用二分查找 */
search_result_t binary_search_generic(
    const void *key,        /* 要查找的键值 */
    const void *base,       /* 有序数组 */
    size_t nmemb,           /* 元素个数 */
    size_t size,            /* 元素大小 */
    cmp_func_t cmp          /* 比较函数 */
);

/* 通用线性查找 */
search_result_t linear_search_generic(
    const void *key,
    const void *base,
    size_t nmemb,
    size_t size,
    cmp_func_t cmp
);

#endif /* SEARCH_H */

这里我加了一个search_result_t结构体来返回查找结果。为什么不用简单的指针返回？因为有时候调用者不仅想知道「找没找到」，还想知道「在哪个位置」。一个结构体打包返回，比用输出参数更清晰。

比较函数的设计要点

比较函数是整个通用接口的灵魂。我见过很多新手在这里翻车，所以专门说一下。

比较函数的约定是：

• 如果 a < b，返回负数
• 如果 a == b，返回0
• 如果 a > b，返回正数

举个例子，比较两个int：

int cmp_int(const void *a, const void *b) {
    int ia = *(const int *)a;
    int ib = *(const int *)b;
    
    /* 注意：不要直接返回 ia - ib，可能有溢出风险 */
    if (ia < ib) return -1;
    if (ia > ib) return 1;
    return 0;
}

对于结构体比较，也很简单：

typedef struct {
    int id;
    char name[32];
    float score;
} student_t;

int cmp_student_by_id(const void *a, const void *b) {
    const student_t *sa = (const student_t *)a;
    const student_t *sb = (const student_t *)b;
    
    if (sa->id < sb->id) return -1;
    if (sa->id > sb->id) return 1;
    return 0;
}

通用接口的使用示例

光说不练假把式。我们来看一个完整的例子：

#include "sort.h"
#include "search.h"
#include <stdio.h>

int main() {
    int arr[] = {34, 7, 23, 32, 5, 62};
    size_t n = sizeof(arr) / sizeof(arr[0]);
    
    /* 排序 */
    sort_generic(arr, n, sizeof(int), cmp_int);
    
    /* 查找 */
    int key = 23;
    search_result_t res = binary_search_generic(
        &key, arr, n, sizeof(int), cmp_int
    );
    
    if (res.found) {
        printf("找到了！索引：%zu，值：%d\n", 
               res.index, *(int *)res.data);
    } else {
        printf("没找到\n");
    }
    
    return 0;
}

你看，整个流程非常清晰。不管数组里存的是什么类型，接口调用方式完全一样。

算法接口的知识体系

为了让大家更直观地理解，我画了一张图：

接口设计中的几个坑

最后，我把自己踩过的坑总结一下，希望能帮大家少走弯路。

常见问题	错误做法	正确做法
比较函数溢出	return a - b	用if判断，避免整数溢出
类型转换错误	直接解引用void*	先转成具体类型指针再解引用
忽略元素大小	假设所有元素都是4字节	始终使用size参数进行指针运算
回调函数不匹配	比较函数签名不一致	严格遵循cmp_func_t定义

总结

通用算法接口的设计，说白了就是三件事：

• 用void*处理数据，不关心具体类型
• 用回调函数处理比较，把逻辑交给调用者
• 用size_t处理大小，保证内存操作的正确性

这套设计思路不仅适用于排序和查找，还可以扩展到其他算法——比如树结构的遍历、哈希表的操作等等。掌握了这个模式，你写出来的代码就会更通用、更易维护。

好了，今天的内容就到这里。希望大家在实际项目中能灵活运用这些接口设计思路。

---