一、库的接口设计：从原则到实践

接口设计这件事，说白了就是「让别人用得舒服，让自己改得轻松」。我做了十几年库开发，踩过的坑比写过的代码还多。今天咱们就聊聊，怎么设计一个让人想给你点赞的库接口。

1. 头文件设计原则

头文件是库的门面。用户第一眼看到的就是它。我见过太多头文件写得像天书的项目，说实话，那体验真的很糟糕。

具体来说，有这几个要点：

• 最小暴露原则：能放在 .c 里的就别放在 .h 里。内部结构体、内部宏定义，统统藏起来。
• 自包含原则：每个头文件都应该能独立编译。不要出现「用户包含 A.h 还得手动包含 B.h」的情况。
• 防重复包含：用 #pragma once 或者传统的头文件卫士。

// 一个好头文件的例子
#pragma once

#include <stdint.h>  // 自包含，用户不用再手动包含

#ifdef __cplusplus
extern "C" {
#endif

// 只暴露公共类型
typedef struct MyContext MyContext;

// 只暴露公共函数
MyContext* my_create(void);
void my_destroy(MyContext* ctx);
int my_do_something(MyContext* ctx, int param);

#ifdef __cplusplus
}
#endif

2. API 设计模式

API 设计没有银弹，但有几个模式我反复在用，效果不错。

2.1 句柄模式（Handle Pattern）

这是 C 语言里最常见的模式。用户不关心内部结构，只拿一个不透明指针操作。

// 句柄模式示例
typedef struct DatabaseHandle DatabaseHandle;

DatabaseHandle* db_open(const char* path);
void db_close(DatabaseHandle* db);
int db_query(DatabaseHandle* db, const char* sql);

为什么用这个模式？说白了，就是解耦。用户改不了你的内部数据，你也改不了用户的代码。各玩各的，互不干扰。

2.2 回调模式（Callback Pattern）

回调函数是 C 语言里实现「反向调用」的唯一方式。我习惯把回调设计成「事件驱动」的风格。

// 回调模式示例
typedef void (*on_data_callback)(void* user_data, const char* data, int len);

void listener_set_callback(on_data_callback cb, void* user_data);
void listener_start(void);
void listener_stop(void);

2.3 工厂模式（Factory Pattern）

当你的库需要支持多种实现时，工厂模式就派上用场了。比如一个日志库，可以支持文件日志、控制台日志、网络日志。

// 工厂模式示例
typedef struct Logger {
    void (*log)(struct Logger* self, const char* msg);
    void (*destroy)(struct Logger* self);
} Logger;

Logger* file_logger_create(const char* path);
Logger* console_logger_create(void);
Logger* network_logger_create(const char* host, int port);

3. 回调函数接口的细节

回调函数看着简单，但坑不少。我总结了几条铁律：

• 永远提供 user_data 参数：这样用户可以在回调里访问自己的上下文。
• 明确回调的线程环境：是在哪个线程调用的？能不能阻塞？这些都要在文档里写清楚。
• 考虑回调的注册和注销：用户可能在回调执行过程中注销回调，这个场景要处理好。

// 一个健壮的回调接口设计
typedef struct {
    void (*on_event)(void* user_data, int event_type, void* event_data);
    void* user_data;
} EventHandler;

// 注册回调
int event_register_handler(EventHandler* handler);

// 注销回调（保证线程安全）
int event_unregister_handler(EventHandler* handler);

4. C 与 C++ 混合编程

这个问题几乎每个做库的人都会遇到。你的库是 C 写的，但用户可能用 C++ 调用。或者反过来。

4.1 在 C 头文件中支持 C++

这个很简单，用 extern "C" 包裹一下就行：

#ifdef __cplusplus
extern "C" {
#endif

// 所有 C 接口声明

#ifdef __cplusplus
}
#endif

4.2 在 C++ 中调用 C 库

C++ 调用 C 库时，要注意几个问题：

• 名字修饰：C++ 编译器会对函数名做修饰（mangling），而 C 编译器不会。所以必须用 extern "C" 告诉 C++ 编译器「别修饰这个函数名」。
• 异常安全：C 代码里不要抛出异常，C++ 代码里捕获异常时要注意栈展开。
• 内存管理：谁分配的内存谁释放。C 库分配的内存，不要用 C++ 的 delete 释放。

// C++ 封装 C 库的示例
#include "my_c_library.h"
#include <memory>

class MyCppWrapper {
public:
    MyCppWrapper() : ctx_(my_create(), my_destroy) {}
    
    void doSomething(int param) {
        int ret = my_do_something(ctx_.get(), param);
        if (ret != 0) {
            throw std::runtime_error("my_do_something failed");
        }
    }
    
private:
    std::unique_ptr<MyContext, decltype(&my_destroy)> ctx_;
};

4.3 在 C 中调用 C++ 库

这个稍微麻烦点。C 不能直接调用 C++ 代码，所以需要写一层 C 风格的包装。

// C++ 实现，暴露 C 接口
// wrapper.cpp
#include "cpp_library.h"

extern "C" {
    void* cpp_create() {
        return new CppLibrary();
    }
    
    void cpp_destroy(void* obj) {
        delete static_cast<CppLibrary*>(obj);
    }
    
    int cpp_process(void* obj, int input) {
        return static_cast<CppLibrary*>(obj)->process(input);
    }
}

5. 知识体系总览

下面这张图总结了本章的核心内容，方便你快速回顾：

6. 总结

接口设计这件事，说到底就是「为用户着想」。你想想看，如果别人用你的库时，头文件清晰明了，API 命名一致，回调不会莫名其妙崩溃，C 和 C++ 调用都顺畅——那人家肯定会觉得「这个库的作者很靠谱」。

我个人习惯在写库之前，先花 30% 的时间设计接口。磨刀不误砍柴工，接口设计好了，后面的实现就是水到渠成的事。

---