有退出计划的版本化
新增版本容易，移除版本需要知道谁仍在调用。公告下线前，先按版本和客户端埋点统计请求。
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.example.com/migrate-v2>; rel="deprecation"步骤
- 定义并文档化新版本的变更、迁移指南和兼容边界，在路径或媒体类型中标识版本。
- 新旧版本并行运行，尽量共享数据，旧版本行为保持不变。
- 按版本和客户端统计请求，联系仍使用旧版本的客户端所有者并提供迁移支持。
- 添加 Deprecation 与 Sunset 头及文档日期，监控错误响应与支持渠道中的迁移阻塞。
- 只有流量归零或公告日期到达且有明确风险接受后，才移除旧版本。
验证
- 指标显示哪些客户端仍在使用旧版本。
- 新版本通过契约与集成测试。
- 弃用头与文档已上线。
- 剩余消费者已确认迁移计划。
- 下线返回文档化错误，支持路径已更新。
决策点
路径版本 /v2/ 更直观、路由简单；有强媒体类型约定的组织可使用媒体类型版本。存在剩余流量时，除非消费者已知、已通知并明确接受中断，否则应延长截止日期。
避免版本蔓延
每个版本都有维护成本。优先使用增量、向后兼容的变更。不可避免的破坏性变更应在发布新版本前定义重叠窗口与移除标准，而不是事后决定。