API 版本演进如何避免破坏客户端？兼容性、弃用与迁移实战
API 演进最危险的误区，是认为“服务端部署成功”就代表变更安全。服务端可以在几分钟内升级，移动端、第三方客户和内部批处理却可能数月不更新。一个 API 一旦有独立生命周期的消费者，就必须把旧契约当作仍在运行的生产代码管理。
1. 版本号不是兼容性的替代品
给每次修改都创建 /v2 看似安全，长期会产生多套 Controller、文档、监控和业务逻辑。更合理的原则是：
- 兼容性新增尽量在当前版本演进。
- 无法兼容的语义变化才引入新主版本。
- 新旧版本共享领域逻辑，只在边界做适配。
- 每个旧版本都有明确负责人、使用量和下线计划。
版本化解决的是“无法同时满足新旧契约”的问题，不应掩盖缺少契约设计。
2. 什么算破坏性变更
常见破坏性变化包括：
- 删除或重命名响应字段。
- 改变字段类型，例如数字变字符串。
- 将可空字段改为必填，或把缺失变为空数组。
- 缩小枚举取值，或新增值但客户端使用了穷举且无兜底。
- 改变时间、金额、精度和时区语义。
- 修改默认排序、分页稳定性或幂等行为。
- 原先返回 200 的场景改为 404/409，客户端未准备。
- 增加请求必填字段或收紧校验规则。
“只新增一个响应字段”通常向后兼容，但旧客户端若使用严格反序列化并拒绝未知字段，仍会失败。兼容性是生产者和消费者共同属性，不能只看 OpenAPI 差异。
3. 兼容性矩阵
| 变更 | 对旧消费者 | 对新消费者/旧服务端 | 推荐做法 |
|---|---|---|---|
| 响应新增可选字段 | 通常兼容 | 不涉及 | 客户端忽略未知字段 |
| 请求新增可选字段 | 兼容 | 新客户端调用旧端时字段可能被忽略 | 明确默认语义 |
| 响应删除字段 | 破坏 | 不涉及 | 先弃用，再新版本移除 |
| 请求新增必填字段 | 破坏 | 旧服务端可能不理解 | 双读默认值或新版本 |
| 新增枚举值 | 可能破坏 | 不涉及 | 客户端必须 unknown 兜底 |
| 类型或单位变化 | 破坏 | 破坏 | 新字段或新主版本 |
请求和响应兼容方向不同。发布时还要考虑滚动升级窗口：新实例和旧实例同时存在，新客户端可能随机请求到旧实例，因此数据库和消息 Schema 都要支持混合版本。
4. 三种常见版本方式
4.1 URL 版本
GET /api/v1/orders/123
GET /api/v2/orders/123优点是直观、易于路由、缓存和文档；缺点是容易复制整套资源，误导团队把任何变化都变成新 URL。适合公开 API 的主版本。
4.2 Header 版本
API-Version: 2026-07-01URL 更稳定，可按日期版本表达能力；但调试、浏览器访问、网关缓存键和文档工具需要显式支持 Header。若 CDN 未把版本 Header 纳入缓存键，可能把不同版本响应混淆。
4.3 媒体类型版本
Accept: application/vnd.example.order-v2+json符合内容协商思想，但对多数业务团队较复杂，网关、SDK 和运维可见性不如 URL 直观。
选哪种不是核心，关键是组织统一。不要同时在 URL、Header 和查询参数中维护三套规则。
5. Expand and Contract：无停机演进
假设需要把 name 拆成 firstName 和 lastName。直接重命名会破坏旧客户端。可分阶段：
阶段 1 Expand
服务端保留 name，新增 firstName/lastName
写入时同时维护新旧表示
阶段 2 Migrate
回填历史数据
新客户端读取新字段
监控旧字段使用量
阶段 3 Contract
停止维护旧字段
经过弃用窗口后，在新主版本删除 name同样的方法适用于数据库列、事件 Schema 和缓存结构。关键是任何滚动升级时刻，新旧实例都能读写当前数据。
双写有失败和语义偏差风险。若两个字段位于同一数据库行，可在一个事务中更新；若跨系统，应使用 Outbox、对账和幂等机制，而不是假设两次网络调用原子成功。
6. 字段演进的具体规则
金额
不要从 12.34 浮点数静默改为以分为单位的整数。新增明确字段：
{
"amount": 12.34,
"money": { "currency": "CNY", "minorUnits": 1234 }
}旧字段进入弃用期，新字段文档说明精度、货币和舍入规则。
时间
明确时区和格式，优先使用 ISO 8601 带 offset/UTC：
{ "createdAt": "2026-07-12T10:30:00.123Z" }不能把“北京时间无时区字符串”改成 UTC 字符串而保持字段名不变，这属于语义破坏。
枚举
服务端新增 PARTIALLY_REFUNDED 后，旧客户端可能 switch 崩溃。客户端模型应保留 UNKNOWN：
default -> OrderStatus.UNKNOWN;若新增值会改变业务决策，仅靠 UNKNOWN 还不够，需要新版本或能力协商。
7. 版本适配层不要复制业务逻辑
推荐结构：
V1 Controller -> V1 Request Mapper --+
+-> Application Service -> Domain
V2 Controller -> V2 Request Mapper --+
Domain Result -> V1 Response Mapper
-> V2 Response MapperV1、V2 只负责协议差异。库存校验、权限和事务规则集中在应用与领域层。如果复制两个 Service，修复一个版本的漏洞时很容易漏掉另一个版本。
适配层可能需要补默认值或转换语义。所有“为了兼容旧版本”的特殊规则应有注释、指标和删除条件，避免成为永久隐式行为。
8. 契约测试与变更门禁
OpenAPI Diff 可在 CI 中识别删除字段、增加必填参数和状态码变化，但 Schema 差异无法发现所有语义变化。还需要：
- 生产者契约测试：验证响应符合公开 Schema。
- 消费者驱动契约：关键消费者声明自己依赖的字段和交互。
- 旧 SDK 回归测试：用仍在支持期的客户端调用新服务端。
- 滚动升级测试：新旧实例共享数据库，混合处理请求。
- 真实流量回放或影子请求：比较新旧版本响应差异。
契约测试不应把所有响应字段全部固定，否则任何兼容新增都会导致测试脆弱。消费者只声明真正依赖的部分。
9. 弃用不是发一封通知
完整弃用流程：
- 在文档、响应 Header 和开发者门户标记 deprecated。
- 提供迁移指南、替代接口、SDK 与截止日期。
- 按 clientId、版本和路由监控真实调用量。
- 主动联系仍有流量的消费者，处理阻塞点。
- 截止日前先在测试环境和小范围客户端验证拒绝行为。
- 下线后保留快速回滚能力和短期观测。
可使用标准化提示：
Deprecation: true
Sunset: Tue, 30 Jun 2027 00:00:00 GMT
Link: <https://developer.example.com/migrations/orders-v2>; rel="deprecation"仅看总调用量不够。一个月只调用一次的财务关账任务可能比高频测试客户端更关键。
10. 能力协商有时优于版本爆炸
对于可选能力，客户端可显式声明支持项：
Client-Capabilities: order-discount-v2,partial-refund服务端只对支持能力的客户端启用新语义。能力协商适合少量正交特性，不适合数十个互相依赖的开关，否则组合数量会失控。主资源模型发生根本变化时，仍应升级主版本。
11. 常见失败模式
- 修改字段名后让网关临时做文本替换，忽略嵌套和语义。
- 永久维护 v1/v2 两套业务代码，没有退出机制。
- 默认排序变化却未加入唯一 tie-breaker，导致分页重复漏项。
- 服务先使用新数据库列，旧实例回滚后无法读取。
- 只通知接口负责人，没有识别真实调用方。
- 把测试环境无流量误认为生产已无人使用。
- 新错误码导致旧客户端穷举失败。
12. 发布检查清单
- 变更对现有请求、响应、状态码和语义是否兼容？
- 客户端是否会拒绝未知字段或枚举值？
- 滚动升级期间新旧实例能否共享数据？
- 是否能用新增字段和双读过渡，而不是原地改类型？
- 新旧版本是否共享同一业务核心？
- CI 是否执行 Schema Diff、契约测试和旧 SDK 回归？
- 是否按真实 clientId 监控旧版本调用？
- 弃用是否有迁移文档、截止日期、负责人和回滚方案？
- 网关与 CDN 的缓存键是否包含版本维度？
- 下线后是否仍有一段时间的告警和恢复预案？
安全演进 API 的核心是让变化可并存：先扩展，再迁移，最后收缩。版本号只是对无法兼容变化的命名；真正保护客户端的是稳定语义、混合版本验证、可观测的弃用流程和严格的契约门禁。