api-versioning

该 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 时间线。