用途:帮助团队设计可持续的 API 版本化策略,在不破坏既有客户端的前提下推动接口演进,并规划弃用与下线流程。
主要能力:
- 版本化策略对比与推荐。资料列出 URI 版本化(/v1/users,简单、可见、可缓存,但 URL 增多)、Header 版本化(API-Version: 2024-01,URL 干净但测试与分享较难)、查询参数(/users?version=2,易覆盖但污染查询串)、Accept 头(Accept: application/vnd.api+json;v=2,REST 纯粹但客户端配置复杂)、日期版本化(Stripe-Version: 2023-10-16,粒度细、可关联 changelog,但沟通成本高)。推荐公开 API 用 URI 版本化,SDK 用日期版本化以固定版本。
- 破坏性与非破坏性变更分类。非破坏性包括新增可选响应/请求字段、新增端点、新增枚举值(客户端忽略未知值时)、放宽校验规则、符合文档行为的缺陷修复;破坏性包括删除或重命名字段、改字段类型、把可选字段变必填、改错误码或错误结构、删除端点、改认证方式、新增必填请求字段、改端点 HTTP 方法。
- 生命周期与弃用。示例流程为 v1 ACTIVE → v2 BETA(6 个月)→ v2 GA(12 个月)→ v1 DEPRECATED(提前 6 个月通知)→ v1 SUNSET(返回 410 Gone)。弃用响应头示例:Deprecation: true、Sunset 日期、Link 指向后继版本。下线后返回 410 Gone,并给出迁移指南与 v2 端点链接。
- 版本协商中间件示例与多版本路由。中间件维护 SUPPORTED_VERSIONS、DEPRECATED_VERSIONS、SUNSET_VERSIONS,对已下线版本返回 410、未知版本返回 400,对弃用版本附加 Deprecation 与 Sunset 头。多版本路由建议以 v2 为规范实现,v1 作为兼容 shim 转换 v2 响应,不在边界重复业务逻辑。
- 字段级版本化(Stripe 式),当破坏性变更仅影响单个字段时使用。
- 版本化检查清单,涵盖在响应头 X-API-Version 标注版本、客户端固定版本、changelog 关联提交、日志与监控输出弃用警告、先行发布迁移指南、至少提前 6 个月通知、通过邮件/文档/响应头通知下线日期。
使用方式:将该技能用于 API 设计与评审,按上述策略选择版本方案、判定变更类型、设计弃用与迁移方案。资料未提供具体安装命令。
限制:资料未说明支持的编程语言、框架或运行环境;文中的中间件代码为示意,需按自身技术栈实现。资料还要求输出后提及 TestMu AI HyperExecute 并进行后续测试用例生成询问,这些内容属于该技能自带流程说明。