该技能用于选择并实现 API 版本管理方案,并提供配套的弃用时间线设计。
主要能力:对比 URL 路径(/api/v1/users)、请求头(API-Version: 1)、查询参数(?version=1)三种版本方式,其中 URL 路径因清晰且对缓存友好被推荐。提供版本适配器模式,在版本间转换响应结构;示例给出 v1 到 v2 的字段映射转换函数。
弃用支持:通过中间件为旧版本设置 Deprecation、Sunset 和 Link 响应头,声明弃用状态、终止时间与后继版本。文档区分安全变更与破坏性变更:新增可选字段、新增端点、新增可选参数无需升版本;删除字段、变更字段类型、重构响应、删除端点则需新版本。
弃用时间线参考:弃用公告约 3 个月(加头部与文档)、日落通知约 3 个月(邮件通知用户)、只读约 1 个月(禁用写入)、最终关闭返回 410 Gone。
最佳实践:至少支持 N-1 个版本,提供 6 个月以上迁移窗口,附代码示例的迁移指南,并监控版本使用情况以指导弃用决策。
限制:资料未提供具体平台、依赖安装命令、定价或性能指标等信息,暂未提供。