📚 课程目录第3章接口集成原则

接口集成原则：API设计、版本兼容性、错误处理

接口集成这事儿，说白了就是让不同语言、不同系统之间的加密SDK能顺畅地“对话”。我见过太多团队花大把时间调密码算法，最后却栽在接口集成上——参数名不一样、版本对不上、报错信息看不懂。这一章咱们就聊聊怎么把接口层设计得既稳健又好维护。

API设计：从调用者的视角出发

好的API设计跟好的门锁一样——开锁的人不需要知道锁芯长什么样。调用者只关心三件事：我要传什么参数、能拿到什么结果、出错了怎么办。

核心原则：接口契约先行。先定义好C语言头文件或IDL，再去做语言绑定，千万别倒过来。

我记得在一个跨平台项目中，我们先用C语言定了核心结构体和函数签名，然后才写C++和Python绑定。结果发现Python那边需要把字节数组转成bytes，而C语言只能传指针和长度——这个差异一开始没在契约里写清楚，后来绑定代码改了三轮。所以我现在养成了习惯：每个接口函数旁边的注释里写清楚参数的所有权和生命周期。

设计要点清单

参数命名统一：所有语言绑定用同一个名字（比如 ciphertext 不要一会叫 encrypted 一会叫 ct）
输入输出分离：用 in / out / inout 标记方向，Java和Go里尤其重要
不暴露内部状态：所有加密上下文用句柄(handle)传递，别让调用者直接操作结构体
资源释放明确：谁分配谁释放，Java里用 AutoCloseable，Python里用上下文管理器

一个小技巧：在C头文件的每个函数声明前加一行注释 //! Transfer: caller owns output 或 //! Transfer: callee owns input，这样做语言绑定时不用再猜内存该谁管。

版本兼容性：别让用户升级就崩

加密SDK最怕什么？怕你升级一个补丁，结果用户的老代码全部报错。版本兼容性不是锦上添花，是生死线——很多金融系统几年才做一次升级。

我自己踩过最大的坑是某个对称加密接口：V1版本里 decrypt 函数返回值是解密后的明文长度；V2版本我头脑一热把它改成了状态码，0代表成功，真正的长度改由参数指针返回。结果客户那边所有调用V1的Java代码全崩了，回退花了三天。从那以后我确定了接口兼容性的铁律。

版本管理策略

变更类型	兼容性要求	例子
新增函数	完全向后兼容	增加`compute_hmac`，旧函数不变
新增可选参数	向后兼容（设默认值）	`encrypt(data, key, nonce=None)`
修改返回值语义	破坏性变更，必须大版本	返回值从长度改为错误码
删除函数或参数	不允许，除非大版本大更新	废弃后用`@deprecated`警告两个版本
修复安全漏洞	尽量保持接口不变，只改实现	修正算法实现，不改函数签名

注意：版本号一定要暴露给调用者。很多SDK只发布二进制，用户根本不知道当前链接的是哪个版本。我建议每个语言绑定都提供一个 sdk_version() 函数，返回主版本、次版本、补丁号。

还有一种常见的做法是运行时检测：在初始化阶段检查调用者传的 api_version 参数，如果超出SDK支持的范围直接返回错误。嗯，这个方案虽然安全，但使用起来有点啰嗦。我更推荐在文档里标明兼容版本范围，配合静态链接时编译期断言。

错误处理：让失败路径可预测

错误消息不会写？很多SDK的错误处理就是返回一个整数，然后让用户去查表。我见过最极端的案例：一个哈希库返回-1表示“失败”，但-1到底是内存不足还是算法不支持？没人知道。

好的错误处理应该做到三点：信息完整、语言原生、安全无泄漏。

错误码与异常映射表

C语言：用int返回错误码，同时提供一个 const char* get_last_error_msg() 函数获取中文错误描述
Java：把错误码映射为自定义异常，比如 CryptoException，并携带错误码和消息
Python：自定义异常类继承 Exception，附加 error_code 属性
Go：返回 error 接口，用 errors.New 或 fmt.Errorf 包含上下文

// C头文件示例
typedef enum {
    CRYPTO_OK = 0,
    CRYPTO_ERR_INVALID_ARGUMENT = 1,
    CRYPTO_ERR_MEMORY = 2,
    CRYPTO_ERR_DECRYPT_FAILED = 3,
    CRYPTO_ERR_INTERNAL = 99
} crypto_error_t;

crypto_error_t crypto_decrypt(
    const uint8_t* ciphertext,
    size_t ct_len,
    const uint8_t* key,
    size_t key_len,
    uint8_t* plaintext,
    size_t* pt_len
);

对于错误消息，我一向建议把核心错误码的枚举值和描述文字写在同一个头文件里，这样不同语言绑定可以直接读取或硬编码，不用单独维护一份文档。

还有件事容易被忽略：错误处理不要泄露敏感信息。比如解密失败时，错误消息里不要写“RSA private key PKCS#1 v1.5 padding incorrect”，因为攻击者能拿这个信息做盲测。安全的做法是统一返回“解密失败”，内部日志里才记录详细原因。

我曾经帮一个客户审计他们的SDK，发现Python绑定里解密出错时直接把异常字符串传给用户，里面直接暴露了OpenSSL的错误栈——里面有密钥ID。嗯，那场景我现在想起来还冒冷汗。

一个完整的集成原则框架

最后我画张图，把刚才说的三点串起来。你在设计接口时可以参考这个分层结构：最下层是C核心，中间是语言绑定层，最上是应用层。每一层都有自己的契约和错误处理规则。

你仔细看这张图就能发现：三个原则不是独立的。API设计决定了版本兼容有多容易改，版本兼容又决定了错误处理的升级策略。比如你要给一个API加个新参数，如果设计时用了可选参数，那就不算破坏性变更；但如果设计时是顺序传参，就得开新版本，然后在错误处理里告诉用户“此参数已废弃”。

总之，接口集成没那么玄乎，就是约定、约定、再约定。把这三块想清楚，你的加密SDK绑定基本不会出大乱子。