（2420期）api-versioning – API 版本控制与迁移最佳实践

API 版本控制与迁移最佳实践 开源社区出品的 API 版本控制指南，提供 4 种版本策略与弃用迁移方案，帮助团队实现 API 平滑演进与生命周期管理。 使用说明 该 Skill 是一份系统全面的 API 版本控制最佳实践文档，旨在帮助开发团队制定稳健的 API 演进策略。核心用法涵盖四大版本化策略的深度解析：URL 路径版本（最适合公开 API）、Header 版本（适合内部协调）、Query 参数（适合原型设计）以及内容协商（适合企业级 REST 合规），并详细阐述了语义化版本在 API 场景中的应用规则（仅主版本号出现在 URL，次版本和修订版通过变更日志传达）。 文档提供了完整的变更分类体系，明确区分破坏性变更（字段删除、类型修改、端点移除等必须升级主版本）与非破坏性变更（新增可选字段、性能优化等可在同版本内发布）。其显著优点在于提供了工业级的弃用管理流程：从公告阶段（通过 Sunset Header 和 RFC 8594 标准标记）、过渡期监控（最少 12 个月公开 API 支持）到最终退役（返回 410 Gone 并提供迁移指南），形成闭环治理。同时详细阐述了适配器模式、外观模式、版本化控制器和网关路由四种迁移架构，以及多版本共存的工程实践（业务逻辑版本无关、序列化版本特定、最多同时维护 2-3 个版本）。 潜在局限性包括：作为 T3 来源的社区文档，缺乏大型技术厂商的官方背书；所有代码示例（FastAPI、Express 等）均为演示性质，不能直接复制到生产环境，需要根据实际技术栈和框架进行适配；文档偏重设计规范而非自动化工具，不提供具体的版本路由中间件或迁移工具链。 适合目标群体包括：负责 API 架构设计的后端工程师、制定技术标准的架构师、管理 API 生命周期的产品经理，以及需要维护历史版本兼容性的企业开发团队。特别适合正在规划 API 重大变更、设计新 API 版本策略或需要制定弃用路线图的技术团队。 使用风险方面，该 Skill 为纯文档型资产，无代码执行、无网络通信、无数据收集，安全性极高。唯一需要注意的是，文档中的配置示例（如 YAML 网关路由）和代码片段需要根据实际基础设施进行调整，避免直接套用导致的路由冲突或安全策略不匹配。建议结合团队实际的 CI/CD 能力和消费者沟通成本来制定 Sunset 时间线。 原始说明 API versioning strategies — URL path, header, query param, content negotiation — with breaking change classification, deprecation timelines, migration patterns, and multi-version support. Use when evolving APIs, planning breaking changes, or managing version lifecycles.