API 设计的版本兼容性处理

做 API 设计时，最容易被低估的成本不是「怎么写」，而是「以后怎么改」。一个对外接口一旦发布，就会有调用方依赖它的行为，这时候任何改动都可能变成破坏性变更。这篇文章聊聊实践中比较稳妥的版本兼容做法。

什么是破坏性变更

不是所有改动都危险。加一个可选字段、加一个新接口，通常是安全的；但有这么几类改动会直接打断调用方：删除或重命名字段、修改字段类型（比如 int 改 string）、把可选字段改成必填、修改已有字段的语义（哪怕名字和类型都没动）、修改错误码的含义。

其中语义变更最隐蔽：字段还是那个字段，类型也没变，但原来「单位是秒」现在变成「单位是毫秒」，调用方不会收到任何编译错误，上线后才炸。

三种主流兼容策略

第一种是URL 版本，比如 /v1/users 和 /v2/users。优点是直观、隔离彻底，两套接口可以并行运行很久；缺点是维护成本翻倍，而且很多团队一旦上了 v2 就再也不管 v1，最后 v1 变成没人敢删的历史包袱。

第二种是请求头版本，通过 Accept-Version 或自定义头区分。URL 保持干净，但调试时不直观，日志里不看头就分不清调用的是哪个版本。

第三种是加性演进（additive evolution），不显式分版本，靠「只加不改」的纪律来保持兼容：新功能都通过新字段、新接口提供，老字段保留但标记废弃。这种方式对使用方最友好，但对设计者的自律要求最高。

实践中的组合拳

实际项目里很少只用一种。比较务实的组合是：主版本走 URL，次版本走加性演进。破坏性变更才升主版本（v1 → v2），非破坏性的功能增加直接在原版本上叠加。这样绝大多数迭代都不需要开新版本号。

配套要做三件事：

1. 废弃策略要显式。字段废弃时在文档标注 deprecated，同时在响应里加 Deprecation 头或警告字段，给出至少一个季度的过渡期。不要静默删除。

2. 契约测试。把接口的 schema 固化成测试用例，任何改动跑一遍契约测试，破坏性变更会在 CI 阶段就被拦住，而不是等调用方报错。

3. 版本使用量监控。按版本维度统计调用量，才知道 v1 什么时候真的可以下线。没有数据就永远不敢删。

一个容易忽略的点

枚举值也是兼容性陷阱。给枚举加新值，看起来是「只加不改」，但如果调用方的代码是穷举 switch 且没有 default 分支，新值会直接导致异常。所以枚举扩展要提前在文档里说明「客户端必须容忍未知枚举值」。

另外，错误响应的结构也要当作契约的一部分。错误码、错误信息的格式一旦被调用方用来做判断逻辑，改动就是破坏性的。

小结

API 版本兼容的本质是「把变更的成本从调用方转移到提供方」。设计阶段多想一步——这个字段未来会不会变、这个枚举会不会扩——比事后开 v2 便宜得多。真正的兼容性保证不靠文档承诺，靠契约测试和监控数据兜底。