用途:为公开 API、开放平台、第三方 SDK 及长期演进项目设计版本管理与兼容变更策略;内部紧耦合 API、短期项目和早期 MVP 不适用。
主要能力:区分兼容变更(新增可选字段、端点、可选参数、错误码、枚举值,放宽校验,新增 HTTP 方法)与不兼容变更(删除字段或端点、重命名字段、改类型或语义、改必填规则或默认值、改错误结构、状态码、鉴权方式、收紧校验、改分页风格)。提供四种版本表达方式:URL 版本(/api/v1/users)、Header 版本(X-API-Version: 2)、日期版本(Stripe-Version: 2024-01-15)、媒体类型版本(Accept: application/json; version=2),并给出选择建议。
使用方式:按评估模板判断变更兼容性,兼容则直接修改并更新文档,不兼容则升版并保留老版本;随后写迁移指南、发布弃用公告、监控老版本使用率、到期下线。弃用流程分公告、标注(Sunset 头)、警告(Deprecation 头)、下线(返回 410 Gone)四步,示例时间线为 Day 0 发布 v2、Day 90 警告、Day 180 部分错误、Day 365 完全下线。可在 OpenAPI 中用 deprecated: true 标注。
限制与注意:弃用期建议不少于 6 个月;需避免侥幸不升版、删字段当兼容、弃用期过短、无迁移指南、版本数量爆炸、新老逻辑分叉过多、不监控老版本等常见问题。配套模板为 templates/api-version-change-template.md。