18、C语言哈希表库的设计：接口设计原则、头文件设计、API文档编写、错误处理机制
好，咱们今天聊点实在的。前面几章我们把哈希表的原理、冲突处理、动态扩容都掰开揉碎了讲了一遍。但说实话，光会写算法还不够——你想想看，真正干活的时候，谁会把一个哈希表算法从头到尾抄一遍？我们都是用现成的库。
那问题来了：怎么设计一个让别人用得爽、自己维护起来也不痛苦的哈希表库？
这一章，我就以自己这些年写C库的经验，跟你聊聊接口设计、头文件组织、API文档怎么写，还有那个最容易被忽略的——错误处理。嗯，这里面的坑，我踩过不少。
核心观点：一个好的C库，不是功能有多强，而是别人拿到你的头文件，看两眼就知道怎么用。
18.1 接口设计原则：少即是多
我刚开始写库的时候，总想着把功能做全。结果呢？接口一大堆，用户看都看晕了。后来我学乖了——接口设计，少即是多。
具体来说，我总结了三条原则：
- 最小化原则：只暴露必要的接口。内部用的函数，全部用
static或者放到实现文件里。 - 一致性原则：命名风格统一。比如所有创建函数都叫
ht_create，所有销毁函数都叫ht_destroy。 - 防御性原则：接口要能处理非法输入。传个NULL指针进来，不能直接崩掉。
举个例子，我设计哈希表库时，最终只暴露了6个接口：
// 创建与销毁
HashTable* ht_create(size_t capacity, HashFunc hash, CmpFunc cmp);
void ht_destroy(HashTable* ht);
// 增删改查
int ht_insert(HashTable* ht, void* key, void* value);
void* ht_find(HashTable* ht, void* key);
int ht_remove(HashTable* ht, void* key);
// 辅助
size_t ht_size(HashTable* ht);你看，就这么几个。用户拿到手，基本不用看文档就能猜个七七八八。我在项目中遇到过那种接口多达二三十个的哈希表库，说实话，每次用都要翻半天文档，太痛苦了。
小技巧：如果你不确定某个接口该不该暴露，先把它藏起来。等用户真的需要了，再放出来也不迟。
18.2 头文件设计：门面要干净
头文件就是库的“门面”。用户第一眼看到的就是它。所以，头文件一定要干净、整洁、自文档化。
我个人习惯，头文件的结构是这样的：
- 文件头注释：简要说明这个库是干什么的。
- 包含守卫：防止重复包含。
- 前置声明：结构体的不透明类型。
- 函数声明：按功能分组，每组加注释。
- 错误码定义：统一错误处理。
来看看我写的 hashtable.h 长什么样：
#ifndef HASHTABLE_H
#define HASHTABLE_H
#include <stddef.h> // size_t
/* ---------- 错误码 ---------- */
#define HT_OK 0
#define HT_ENOMEM -1 // 内存不足
#define HT_ENOTFOUND -2 // 未找到
#define HT_EEXIST -3 // 键已存在
/* ---------- 不透明类型 ---------- */
typedef struct HashTable HashTable;
/* ---------- 函数指针类型 ---------- */
typedef size_t (*HashFunc)(const void* key);
typedef int (*CmpFunc)(const void* a, const void* b);
/* ---------- 核心接口 ---------- */
// 创建哈希表，capacity为初始容量，hash为哈希函数，cmp为比较函数
HashTable* ht_create(size_t capacity, HashFunc hash, CmpFunc cmp);
// 销毁哈希表，释放所有内存
void ht_destroy(HashTable* ht);
// 插入键值对，成功返回HT_OK
int ht_insert(HashTable* ht, void* key, void* value);
// 查找键对应的值，找到返回value指针，否则返回NULL
void* ht_find(HashTable* ht, void* key);
// 删除键值对，成功返回HT_OK
int ht_remove(HashTable* ht, void* key);
// 返回当前元素个数
size_t ht_size(HashTable* ht);
#endif /* HASHTABLE_H */注意看，我把 HashTable 定义成了不透明类型。用户只能通过指针操作，看不到内部结构。这样做的好处是：实现可以随便改，接口不用变。我曾经因为把结构体定义放在头文件里，导致改一次内部结构，所有用户代码都要重新编译——那叫一个惨。
警告：不要在头文件里暴露内部结构体！除非你想让用户依赖你的实现细节，然后每次改代码都被骂。
18.3 API文档编写：注释即文档
说实话，我见过太多“零注释”的C库了。用户拿到手，一脸懵。我个人习惯是：每个公开函数都要有注释，说明参数、返回值、注意事项。
注释怎么写？我推荐这种风格：
/**
* @brief 插入键值对
* @param ht 哈希表指针，不能为NULL
* @param key 键指针，不能为NULL
* @param value 值指针，可以为NULL
* @return HT_OK 成功
* HT_ENOMEM 内存不足
* HT_EEXIST 键已存在
* @note 如果键已存在，不会覆盖旧值，返回HT_EEXIST
*/
int ht_insert(HashTable* ht, void* key, void* value);这种注释，用 Doxygen 工具可以直接生成漂亮的HTML文档。而且，写注释的过程本身就是在帮你理清接口设计——如果你发现某个函数的注释很难写清楚，那多半是接口设计有问题。
我在项目中遇到过最头疼的事，就是接手一个没有注释的库。每个函数都要去读源码才能知道怎么用。所以，写注释不是给别人看的，是给未来的自己看的。
18.4 错误处理机制：别让用户猜
C语言没有异常机制，所以错误处理全靠返回值。那怎么设计一套好用的错误处理呢？
我的做法是：
- 统一错误码：所有函数返回
int，0表示成功，负数表示错误。 - 错误码有含义：不要只返回 -1，要返回
HT_ENOMEM、HT_ENOTFOUND这种有名字的宏。 - 提供错误描述函数：方便用户打印错误信息。
来看个例子：
// 错误码转字符串
const char* ht_strerror(int err) {
switch (err) {
case HT_OK: return "success";
case HT_ENOMEM: return "out of memory";
case HT_ENOTFOUND: return "key not found";
case HT_EEXIST: return "key already exists";
default: return "unknown error";
}
}
// 用户使用示例
int ret = ht_insert(ht, key, value);
if (ret != HT_OK) {
fprintf(stderr, "insert failed: %s\n", ht_strerror(ret));
return -1;
}你想想看，如果每个函数都返回不同的错误码，用户记都记不住。统一成一套错误码，用户只用记住几个宏，用起来就顺手多了。
避坑指南：我曾经在一个库里，有的函数返回 -1 表示失败，有的返回 NULL，有的返回 0。结果用户写代码时，每个函数都要查文档才知道怎么判断错误。后来我全部统一成 int 返回值，世界清净了。
18.5 知识体系总览
说了这么多，咱们来张图总结一下哈希表库设计的核心要点：
这张图把四个核心要点串起来了。你设计库的时候，就照着这四个方向去思考，基本不会跑偏。
18.6 小结
好，这一章的内容就这些。说白了，设计一个C语言哈希表库，核心就四点：接口要少、头文件要干净、文档要写清楚、错误处理要统一。
这些原则不光适用于哈希表库，你写任何C库都可以套用。我这些年写过的库，凡是遵循这些原则的，用户反馈都很好；凡是偷懒没做到的，最后都成了“历史遗留问题”。
嗯，下一章我们就要动手写代码了。到时候，我会带着你从零开始实现一个完整的哈希表库，把今天讲的这些原则全部用上。