架构与系统设计 / 系统课时
设计 API 的向后兼容演进
设计 API 的向后兼容演进
API 演进的难点不是“把新版本发出去”,而是让旧调用方在尚未升级时仍能继续工作。本篇用兼容字段、弃用周期和版本边界,建立一套可执行的接口变更顺序。
学习目标
- 判断字段新增、删除、改名和语义变化是否会破坏旧调用方
- 设计“先扩展、再弃用、后移除”的兼容演进周期
- 知道什么时候应继续兼容,什么时候应启用新版本
先识别真正的破坏性变更
向后兼容的判断标准是:新服务上线后,按旧契约编写的调用方是否还能得到它能理解的结果。因此,“服务端能处理”不代表“客户端不会坏”。
常见变化可以这样判断:
| 变化 | 通常是否兼容 | 主要风险 |
|---|---|---|
| 响应新增可选字段 | 是 | 严格反序列化客户端可能拒绝未知字段 |
| 请求新增可选字段 | 是 | 服务端必须为缺省情况保留旧行为 |
| 删除或改名现有字段 | 否 | 旧客户端仍会读取或发送原字段 |
| 把可选字段改为必填 | 否 | 旧客户端不会提供该字段 |
| 扩展枚举值 | 不一定 | 穷举式客户端可能遇到未知值 |
| 改变字段含义或单位 | 否 | 结构没变,但业务语义已经破坏 |
用扩展式变更跨过多版本并存期
最稳妥的顺序是先让新旧调用方都能工作,再推动调用方迁移,最后删除旧契约。假设原接口返回 name,现在希望拆成 firstName 和 lastName,不要直接把 name 删除。

在过渡版本中,服务端同时返回旧字段和新字段,并让两者表达同一个业务事实。以下请求假设本地服务已启动在 <PORT>,将其替换为实际端口后执行,实际值可能不同。
curl -s http://localhost:<PORT>/users/42预期输出:
{
"id": 42,
"name": "Ada Lovelace",
"firstName": "Ada",
"lastName": "Lovelace"
}旧客户端继续读取 name,新客户端可以开始使用 firstName 与 lastName。只有当调用方迁移完成并经过一个明确的弃用窗口后,服务端才进入删除旧字段的收缩阶段。
把弃用当成协议而不是注释
弃用周期至少要包含三个信息:从哪个版本开始弃用、替代方案是什么、最早何时移除。如果平台可观测调用方版本,还应先确认旧字段实际使用量已经下降到可接受范围。
对于 HTTP API,可以在文档和响应元数据中同时暴露弃用信息;对于 SDK,还可以在类型或方法上标记 deprecated。关键不是“提醒过”,而是给调用方足够的双栈时间,使发布节奏彼此解耦。
在删除旧字段前,至少检查:
- 旧字段调用量是否已经降到约定阈值
- 关键调用方是否完成迁移和回归验证
- 回滚到上一服务版本时,新旧数据是否仍能互相理解
- 监控和告警是否已经切换到新字段、新错误码或新事件名
版本策略只处理无法兼容的变化
不要把每次小改动都变成 /v2。如果新增可选字段就能满足需求,继续演进现有版本通常更容易维护。只有当新旧语义无法同时成立时,才值得建立新版本边界。
适合新版本的典型场景包括:字段语义彻底改变、资源模型重构、认证方式不兼容、错误模型重写,或必须删除旧行为才能保证正确性。此时应让旧版本继续服务一段迁移期,而不是在发布新版本当天强制所有调用方切换。
真正可维护的 API 演进依赖的是兼容窗口和退出机制:先扩展契约,再观察迁移,最后收缩;版本号只是当兼容已经无法成立时才使用的边界。