接口版本管理：版本号设计与废弃策略
接口版本管理这事儿，说大不大，说小不小。我见过太多团队，一开始觉得「加个版本号多此一举」，结果半年后接口改了，下游模块全崩，排查三天才发现是版本不匹配。嗯，这种痛，经历过一次就记住了。
今天咱们聊聊接口版本号怎么设计，以及如何优雅地处理废弃接口。说白了，就是让你的接口在演进过程中，不把老用户摔下车。
一、版本号的基本设计思路
我个人习惯把接口版本号分成三段：主版本.次版本.修订号。这和语义化版本（SemVer）的思路一致，但用在接口上，含义要更明确。
| 版本段 | 含义 | 变更影响 |
|---|---|---|
| 主版本 | 不向后兼容的变更 | 调用方必须修改代码 |
| 次版本 | 向后兼容的新功能 | 调用方无需修改 |
| 修订号 | 内部修复、优化 | 调用方无感知 |
举个例子：v2.3.1 表示主版本2，次版本3，修订号1。如果我把某个函数的参数类型改了，那就是主版本升级。如果只是新增一个可选参数，那就是次版本升级。如果只是修了个bug，那就是修订号升级。
核心原则：主版本号变更时，老版本接口必须保留一段时间，给下游迁移的时间。
三、如何在代码中嵌入版本号
我建议把版本号定义在接口头文件中，用宏或枚举暴露出来。这样调用方在编译时就能检查版本匹配。
// interface_v2.h
#define INTERFACE_MAJOR_VERSION 2
#define INTERFACE_MINOR_VERSION 3
#define INTERFACE_PATCH_VERSION 1
// 也可以用一个宏统一表示
#define INTERFACE_VERSION "2.3.1"
// 运行时版本检查函数
const char* get_interface_version(void) {
return INTERFACE_VERSION;
}
// 编译时版本检查宏
#define CHECK_INTERFACE_VERSION(major, minor) \
static_assert(INTERFACE_MAJOR_VERSION >= major && \
(INTERFACE_MAJOR_VERSION > major || \
INTERFACE_MINOR_VERSION >= minor), \
"Interface version mismatch!")
调用方可以这样用：
// 在调用方代码中
CHECK_INTERFACE_VERSION(2, 0); // 要求接口版本至少为 2.0
这样如果接口版本不满足要求，编译直接报错，比运行时崩溃强多了。
四、向后兼容的策略
向后兼容说白了就是：老代码不修改，也能正常工作。我总结了几条实战经验：
- 只增不减：不要删除已有的函数、宏、结构体字段。可以新增，但别删。
- 参数只加可选：新参数要设计成有默认值，或者用 NULL 表示「使用旧行为」。
- 返回值只扩不缩：如果返回结构体，新字段加在末尾，且初始化为 0。
- 行为不变：同样的输入，同样的调用顺序，结果必须一致。
小技巧：我习惯在结构体末尾预留一些保留字段，初始化为 0。这样后续扩展时，老代码看到的保留字段还是 0，不会出问题。
// 老版本结构体
typedef struct {
int x;
int y;
int reserved[4]; // 预留字段，初始化为0
} Point;
// 新版本扩展
typedef struct {
int x;
int y;
int reserved[4];
int z; // 新字段，老代码不会访问
} PointV2;
五、废弃接口的处理策略
废弃接口不能直接删，得有个「缓冲期」。我一般分三步走：
- 标记废弃：在头文件中用
__attribute__((deprecated))或注释标明，编译时给警告。 - 保留实现：函数体保留，但内部可以加日志，记录谁还在调用。
- 最终移除：等主版本升级时，一并清理掉。
// 废弃接口标记示例
__attribute__((deprecated("Use new_calc() instead")))
int old_calc(int a, int b) {
// 记录调用日志，方便追踪
log_warn("old_calc() called from %s", __FILE__);
return a + b;
}
调用方编译时会看到类似这样的警告：
warning: 'old_calc' is deprecated: Use new_calc() instead [-Wdeprecated-declarations]
这样调用方就知道该迁移了，但不会立刻编译失败。
注意：废弃接口的文档也要同步更新。我曾经遇到过接口标记了废弃，但文档没更新，新来的同事照着文档写代码，又用上了老接口。嗯，这种坑踩过一次就长记性了。
六、版本管理的流程图
下面这张图展示了接口从创建到废弃的完整生命周期：
七、实战中的避坑指南
我曾经接手过一个项目，接口版本号写在注释里，代码里根本没检查。结果有人改了接口，忘了更新注释，下游模块全按老版本编译，上线就崩。嗯，从那以后我坚持：版本号必须写在代码里，并且要有编译时检查。
还有一次，我们废弃了一个接口，但没加 deprecated 标记，只是口头通知大家别用了。结果三个月后，新来的同事不知道，又用上了。后来我们定了个规矩：废弃接口必须加编译警告，并且要在代码仓库的 README 里公示废弃计划。
我的建议：
- 版本号用宏定义，不要用字符串常量（宏可以在预处理阶段检查）
- 废弃接口保留至少一个次版本周期（比如 v1.x 废弃，v2.0 才移除）
- 每次发布新版本，更新 CHANGELOG，写明哪些接口废弃了
- 提供迁移指南，告诉调用方怎么从老接口迁移到新接口
八、总结
接口版本管理，说白了就是给接口一个「身份证」，让调用方知道你是谁、你多大、你变了没有。向后兼容是美德，废弃接口是责任。别让下游模块因为你的一个改动，半夜爬起来修 bug。
我个人习惯把版本管理当成接口设计的一部分，从第一天就做好。等到项目大了再补，那成本可就高了去了。