备案站点的接口版本管理与兼容性治理

你能回滚代码，但回滚不了用户手机里的 App

Web 端改接口相对安全：前后端一起发布，出问题一起回滚。但只要接口还服务着 App、小程序、第三方对接或者开放平台，情况就完全不同了——老版本客户端会长期存在，你无法强制所有人升级。这就是接口兼容性治理的核心约束。

关键要点

• 判断一个改动是不是破坏性变更，标准是「老调用方不改代码还能不能正常工作」。
• 兼容演进的第一原则是加法优先：加字段安全，删字段和改语义危险。
• 下线接口要走公告、监控、日落三步，不能直接关。
• 客户端要实现「宽容读取」：遇到未知字段忽略，而不是报错。

破坏性变更清单

变更	是否破坏	说明
新增可选字段	否	最安全的演进方式
新增必填请求参数	是	老调用方不传直接失败
删除或重命名响应字段	是	老客户端解析报错或显示空白
修改字段类型	是	数字改字符串是经典事故
收紧参数校验	是	原本能过的请求突然被拒
修改字段语义	是	最隐蔽，格式没变但含义变了
新增错误码	视情况	老客户端可能落入未处理分支
修改分页默认值	是	调用方按旧默认值写死了逻辑

最危险的一类是语义变更：字段名和类型都没动，但「金额」从「元」变成了「分」。接口测试全绿，线上金额全错。这类变更必须当作删除旧字段、新增新字段来处理。

加法优先的演进策略

需要替换一个字段时，用和数据库迁移同样的三步法：扩展 → 切换 → 收敛。

1. 新字段与旧字段并存，服务端同时返回两者。
2. 客户端逐步改用新字段，观察旧字段调用量下降。
3. 旧字段调用量归零且老版本淘汰后，才删除旧字段。

这套节奏和表结构变更完全一致，见 数据库变更与在线 DDL 实践。关键点是三步要分三次发布，合并成一次就失去了随时回滚的能力。

三种版本化方式

方式	示例	优点	代价
路径版本	/api/v2/order	直观、易路由、易灰度	版本多了代码分叉
请求头版本	Api-Version: 2	URL 干净	调试与缓存不直观
参数版本	?version=2	改动最小	容易被缓存与代理忽略

多数中小团队用路径版本就够了。但要提醒的是：版本号不是免费的，每多一个在线版本就多一份维护和测试成本。优先用兼容演进解决问题，版本升级留给真正无法兼容的重构。

接口下线的四步流程

1. 公告：明确下线日期，给调用方留出足够时间。
2. 监控：统计老接口的调用量与来源，知道还有谁在用，指标采集见 可观测性建设。
3. 日落：先返回弃用标记，再逐步降级（限速、部分时段返回错误），观察影响面。
4. 下线：调用量归零后再关闭，并保留一段时间的回滚能力。

跳过第 2 步是最常见的失败原因：以为没人用了，一关就有企业客户打电话过来。

客户端侧的约束

• 宽容读取：解析响应时忽略未知字段，不要用严格模式直接抛异常。
• 兜底渲染：字段缺失时显示占位而不是白屏或崩溃。
• 强制升级开关：提前预埋最低版本控制能力，否则出事时毫无办法。
• 未知错误码兜底：归入通用错误提示，而不是走进未定义分支。

上线节奏与验证

接口变更要按灰度节奏发布，先小比例放量观察错误率与老客户端表现，见 灰度发布与蓝绿部署；兼容性用例应纳入流水线，每次发布自动回归，见 CI/CD 自动化部署。上线后重点盯老版本客户端的错误率曲线，而不只看整体成功率——整体看着正常，老版本可能已经全挂了，前端侧的真实错误采集见 前端性能与错误监控。

常见坑

• 直接改字段类型：老客户端解析崩溃。
• 偷偷改语义：所有自动化测试都发现不了。
• 不统计调用来源就下线：第三方对接方直接受影响。
• 版本无限增长：五个版本同时在线，没人敢动任何一个。
• 只按整体成功率判断：老版本用户已经全部失败却看不出来。

常见问题

什么时候该升大版本，什么时候在原版本上兼容演进？

能用加法解决的，一律在原版本演进。只有当资源模型或语义整体重构、无法在同一套接口里兼容表达时，才升版本。每个在线版本都要长期维护，不要轻易开新的。

老接口要保留多久？

看客户端类型：Web 端通常几周即可；App 要看版本分布，常见做法是等到老版本占比降到很低时再下线，并保留强制升级作为兜底手段。

内部服务之间的接口也需要这么严格吗？

需要，但流程可以简化。内部服务同样存在发布顺序问题：A 先发、B 后发，中间那段时间两边版本不一致。兼容窗口能让两个服务独立发布、独立回滚。

怎么知道还有哪些调用方在用老接口？

在接入层按接口路径、客户端版本、来源标识统计调用量，并在响应里带上弃用标记。这些数据要在公告之前就开始采集，否则公告期结束你依然不知道会影响谁。

资料来源

主流 API 设计与版本管理公开实践资料，以及 HTTP 语义相关标准文档中关于弃用与兼容处理的说明。本文为通用工程说明，仅供参考，具体策略以实际业务与客户端分布为准。