API 兼容性

掌控公共 API 的生命周期：谁在你发布时会受到影响，旧行为还能维持多久，以及客户端如何发现未来的变更。配合 http-api 技能了解当前请求的形态；本技能关注的是时间与承诺。

何时使用

• 添加或移除现有客户端依赖的字段、路由或语义。
• 选择URL、Header 或包版本控制，或决定不采用正式版本而仅通过添加字段的 JSON 扩展。
• 弃用策略：明确的时间线、使用指标（仍有多少客户端调用旧接口？），以及移除的触发条件。

核心理念

• 优先考虑向后兼容性 —— 可选的新字段优于无声的行为变更。
• 明确契约 —— 对关键合作方使用集成测试或消费者驱动的验证。
• 主动沟通 —— 通过变更日志、开发者邮件，在响应中加入符合标准的 Sunset 提示或警告。

避免

• 仅因“我们只需升级版本”就直接破坏，而没有为慢速更新的应用提供迁移方案。
• 在未预留协调窗口期的情况下，改变认证机制或分页逻辑。
• 无使用数据支撑就进行弃用 —— 你可能切断了自己未曾意识到的流量。

破坏前检查清单

• [ ] 受影响对象是谁（仅内部使用？还是第三方）？
• [ ] 是否设置了最短通知期，并在遥测数据异常上升时具备回滚能力？
• [ ] 文档和示例是否在发布日之前完成更新？

完成标准

• 旧版与新版行为均可量化衡量；移除操作基于证据，而非主观猜测。