第4节、SDK的输出接口介绍

做SDK开发，最绕不开的就是输出接口。说白了，你的SDK能不能被上层业务用好，一半看接口设计得好不好。我习惯把输出接口分成三类：直接输出函数、回调机制、事件体系。这三类不是互斥的，很多SDK会混着用。今天我们就一个一个拆开看。

4.1 常见输出函数——最朴素但最常用

输出函数是SDK最基本的出口。比如日志打印、状态查询、结果返回。最简单的形式就是int get_config(char *buf, int len)这类同步接口。

我记得早期做嵌入式SDK时，所有调试信息都靠串口打印。后来产品化之后，客户要求能控制日志级别，于是我们封装了类似log_info/log_error/log_debug的宏。这里有个小坑：

常见的输出函数设计套路：

函数类型	典型签名	用途	注意点
同步查询	int get_version(char* ver, int len)	获取SDK信息	需确保缓冲区足够
日志输出	void log(LogLevel lv, const char* fmt, ...)	调试/跟踪	日志级别过滤，避免性能开销
数据导出	int export_data(void* buffer, uint32_t* size)	批量传出数据	考虑零拷贝、内存管理
错误码返回	int get_last_error(void)	获取错误详情	线程局部存储，防止覆盖

你想想看，这些函数看起来简单，但每个细节都可能影响SDK的健壮性。我个人习惯在函数命名上加上前缀，比如sdk_xx_xx，方便客户在代码里一眼识别。

4.2 回调机制——让业务方掌控时机

回调，说白了就是你把函数指针注册进去，等条件满足时SDK反向调用你。这比轮询优雅多了。我见过不少新手SDK直接把回调函数放在主循环里，结果阻塞了所有任务。

回调机制的典型流程：

1. 注册：业务方调用sdk_set_callback(type, func, userdata)。
2. 触发：SDK内部在合适的时机调用func(userdata, param)。
3. 注销：业务方不再需要时，调用sdk_clear_callback(type)。

我曾经在一个多线程项目里，因为回调注册时没做互斥锁，导致回调列表被并发修改，运行时不定时崩溃。嗯，后来我们加了个读写锁，读多写少时性能影响很小。

回调函数的签名设计也有讲究：

// 错误回调示例
typedef void (*on_error_cb)(int error_code, const char* msg, void* user_data);

// 注册接口
int sdk_register_error_callback(on_error_cb cb, void* user_data);

// SDK内部触发
sdk_event->on_err_cb(ERR_TIMEOUT, "connection lost", sdk_event->user_data);

这里user_data是个关键设计。它允许业务方把上下文带进去，避免用全局变量。我早期做SDK时没加这个参数，后来被客户骂惨了。

4.3 事件体系——数据结构化的消息总线

事件体系比回调更进一步。它通常包含事件源、事件分发器、事件监听器。SDK内部产生各种事件（设备连接、数据到达、错误），分发器根据事件类型派发给已注册的监听器。

为什么要搞这么复杂？你想，回调是一对一的，但实际场景里一个事件可能有多个接收者：比如日志模块要记录、UI要更新、业务逻辑要处理。事件体系就能完美解决一对多。

我设计事件体系时通常会做个优先级队列。比如错误事件要优先于状态事件。这样即使队列积压，关键事件也能尽快被处理。

下面是一段伪代码，展示事件注册和触发的基本思路：

// 事件类型枚举
enum EventType {
    EVENT_DATA_READY,
    EVENT_DISCONNECT,
    EVENT_ERROR
};

// 事件结构
struct Event {
    EventType type;
    uint32_t timestamp;
    void* data;
    size_t data_len;
};

// 监听器
typedef void (*event_handler)(const Event* evt, void* user_data);

// 注册接口
void event_register(EventType type, event_handler handler, void* user_data);

// 触发
void event_fire(const Event* evt) {
    for each listener in list[evt->type] {
        listener.handler(evt, listener.user_data);
    }
}

注意：event_fire如果是同步的，就可能阻塞事件源。所以实践中我常用异步事件队列——事件源入队，分发器在独立线程中出队并调用监听器。

4.4 三类接口的对比与选择

特性	输出函数	回调机制	事件体系
调用方向	业务方主动调用	SDK反向调用业务方	双向：业务方可触发，也可被通知
关系	一对一	一对一	一对多
复杂度	低	中	高
解耦程度	差	较好	最好
典型场景	查询状态、日志	错误通知、进度反馈	多模块协作、复杂逻辑
线程安全要求	一般	较高（注册/调用）	高（队列+分发）

我个人习惯的组合拳是：基础状态查询用输出函数；异步通知用回调；多模块间的事件联动用事件体系。你看看自己的SDK场景，选对组合能省很多维护成本。

4.5 整体结构图

下面这张图展示SDK中三类输出接口的协作关系。注意看数据是怎么流到业务方的：

4.6 避坑指南与最佳实践

• 不要混用同步和异步回调：统一让所有回调在单独线程中执行，否则业务方很难写线程安全的代码。
• 回调注册时一定要保证线程安全：我曾经因为没有加锁，多线程注册/注销导致段错误。
• 事件对象不要用全局静态内存：如果分发器延迟处理，事件数据可能被覆盖。建议堆分配+引用计数。
• 日志输出函数要带格式检查：用编译器属性__attribute__((format(printf, ...)))，防止格式化漏洞。
• 为事件体系留好诊断接口：比如get_pending_event_count()，方便线上排查问题。