SDK接口规范解读：新SDK的接口定义、协议与约束
新SDK的接口定义拿过来的时候，我习惯先看三样东西：接口原型、通信协议、使用约束。说白了，就是搞清楚「怎么调」、「传什么」、以及「不能踩哪些坑」。这一章我们就把新SDK的接口规范拆开揉碎了讲。
你可能会问，旧SDK不是调得好好的，为什么要换？嗯，换接口一般都伴随着协议升级、性能要求、或者安全补丁。我个人遇到过好几次，旧SDK的接口定义过于松散，导致联调时各种歧义。新SDK在这块做了不少收敛工作。
接口定义：新SDK的核心API一览
新SDK对外暴露了7个核心接口，我把它们归纳为三类：生命周期管理、数据传输、配置获取。下表是完整的接口原型，你最好逐条对照着看。
| 接口名称 | 用途 | 参数说明 | 返回值 |
|---|---|---|---|
SDK_Init() |
初始化SDK运行环境 | config: SDKConfig结构体 | int32：0成功，非0错误码 |
SDK_RegisterCallback() |
注册事件通知回调 | cb: 回调函数指针，mask: 事件掩码 | int32：0成功 |
SDK_UnregisterCallback() |
注销已注册的回调 | 无 | int32：0成功 |
SDK_SendData() |
向服务端发送业务数据 | data: 字节数组，len: 数据长度 | int32：0成功 |
SDK_RecvData() |
轮询接收服务端推送 | outBuf: 输出缓冲区，bufSize: 缓冲区大小 | int32：实际接收字节数，负数表示异常 |
SDK_GetVersion() |
获取当前SDK版本号 | 无 | const char*：版本字符串 |
SDK_Cleanup() |
释放SDK占用的资源 | 无 | void |
SDK_Init的参数结构体变化最大，旧版本用的是平铺的参数列表，新版本全部收拢到一个结构体里了。
我第一次用新SDK的时候，差点在SDK_RecvData上翻车。旧SDK是同步阻塞接收，新SDK改成了非阻塞轮询。返回值小于0表示异常，等于0表示无数据，大于0才是实际接收长度。这个语义变化，很多人一开始没注意，结果线上出现了空循环，CPU直接被打满。
协议约束：序列化与传输格式
新SDK统一使用Protobuf作为序列化方案。旧SDK用的是自研的二进制JSON混合格式，说实话，解析起来很痛苦。新SDK把这块标准化了。
先看一段protobuf的消息定义示例：
syntax = "proto3";
package sdk.v3;
message BusinessData {
uint32 msg_id = 1;
uint64 timestamp = 2;
bytes payload = 3;
map<string, string> extensions = 4;
}
message SDKConfig {
string endpoint = 1;
uint32 timeout_ms = 2;
bool enable_debug = 3;
repeated string allowed_ips = 4;
}
这个定义有一个关键变化：extensions字段。旧SDK不支持扩展字段，每次新增参数都要改协议版本。新SDK用map兜底，只要key-value语义不变，兼容性会好很多。我在项目中遇到过几次因为旧协议字段升级导致重新联调的惨剧，新方案至少避免了字段级别的断裂。
| 对比维度 | 旧SDK协议 | 新SDK协议 |
|---|---|---|
| 序列化方式 | 自研JSON混合 | Protobuf 3 |
| 消息结构 | 固定字段+可选扩展 | 强类型+Map扩展 |
| 传输编码 | UTF-8文本 | 二进制（Length-Delimited） |
| 校验方式 | 运行时JSON校验 | 编译期+运行时双重校验 |
调用约束：线程模型与资源管理
新SDK对调用方做了明确的线程约束。官方文档里提了三句话，但很多人读得太快就跳过了。我把它提炼成以下三条硬性规则：
- 初始化与清理必须在同一个线程：
SDK_Init和SDK_Cleanup不能跨线程调用，否则会导致资源泄漏。 - 回调函数在SDK内部线程触发：
SDK_RegisterCallback注册的回调，会被SDK在一个独立的工作线程里执行。回调里不能做耗时操作，否则会阻塞SDK内部的事件循环。 - 发送和接收不能并发：
SDK_SendData和SDK_RecvData虽然是线程安全的，但如果你同时在两个线程里调用，内部会加锁，性能会直线下降。最好设计成一个生产者线程+一个消费者线程的模式。
你想想看，旧SDK只要求「进程内单例」，对线程模型基本没限制。新SDK这么一改，很多多线程架构就得重新调整了。我记得有一次帮客户做迁移，对方在四个线程里同时调SDK_SendData，结果锁竞争严重，吞吐量反而比旧SDK还低。后来改成单线程发送+队列缓冲，问题就解决了。
接口调用顺序与生命周期
新SDK明确规定了接口的调用次序。上图一目了然：
从上图能看出，新SDK的生命周期是一个明确的闭环：初始化 → 注册回调 → 数据收发（核心业务） → 注销回调 → 清理。违反这个顺序会怎么样？举个例子，你如果在SDK_Init之前调用SDK_SendData，SDK内部会直接返回ERR_NOT_INIT错误码。旧SDK反而是默默创建了一个隐式上下文让你继续跑，但后续行为变得不可预测。
SDK_Init，析构函数里调SDK_Cleanup。这样至少不会有忘记清理的问题。我个人所有迁移项目都会加这么一层，算是防御性编程的底线。
关键约束速查表
最后，我整理了一个速查列表。你可以把它贴在项目文档的封面页，联调时随时对照：
- 线程约束：Init/Cleanup同线程；回调在SDK内部线程触发；发送接收不建议并发。
- 内存约束：
SDK_SendData的数据区在调用返回前不能被释放，SDK是同步拷贝还是引用传递，文档没明确写，我建议你在传递之后等待返回值再释放。 - 超时约束：
SDK_Init传入的timeout_ms只在首次连接时生效，运行期间的心跳超时由SDK内部管理，不需要外部干预。 - 版本兼容：新SDK保证对相同主版本号的接口向前兼容。如果你从v3.0升级到v3.1，接口签名不会变；但如果从v3.x升级到v4.x，就不保证了。
SDK_RecvData在跨平台编译时，如果缓冲区地址不是4字节对齐，部分ARM平台会触发总线错误。迁移到嵌入式系统时，一定要在栈上声明alignas(4)的输出数组，或者用malloc手动对齐。
说一千道一万，接口规范是死的，但迁移场景是活的。新SDK的约束看起来多，其实每条约束背后都有对应的线上事故案例。从旧接口到新接口的过渡，不是「替换函数名」这么简单，而是要把这些规范内化到你的架构设计里。