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

核心用法

本 Skill 是一个纯文档型（T-MD）的 API 版本管理参考指南，系统性地阐述了 API 演进的完整生命周期管理。它提供了四种主流版本管理策略（URL 路径、查询参数、请求头、内容协商）的详细对比与实施示例，定义了重大变更与非重大变更的明确边界，并给出了包含公告、日落期和移除三阶段的废弃流程。文档还涵盖了适配器模式、外观模式等迁移模式，以及多版本并发支持的架构原则。

显著优点

1. 体系化知识：完整覆盖了从版本策略选择、语义化版本应用到客户端通信、SDK 版本对齐的全流程，提供了可操作的实践清单。
2. 工程化指导：包含可直接参考的代码示例（Python/FastAPI、JavaScript/Express）和反模式警告，易于集成到实际开发流程中。
3. 低风险：作为零依赖、零可执行代码的纯文档，不会引入任何依赖项漏洞或运行时性能隐患。
4. 安全意识强：强调了不破坏现有消费者、渐进废弃和使用 RFC 8594 Sunset Header 等现代 Web 最佳实践。

潜在缺点或局限性

1. 纯文档无自动化：作为静态参考文档，不提供自动化的版本检查、代码生成或 CI 集成工具，所有实践均需开发者手动实施。
2. T3 来源可信度有限：作者 wpank 为个人开发者，缺乏大型科技公司或权威标准组织的背书，内容的全面性和准确性未经过广泛的第三方验证。
3. 缺少许可证声明：未包含开源许可证文件，可能限制在企业或合规要求严格的环境中的采纳与分发。
4. 示例未测试：所有代码块均为教学示例，可能未涵盖复杂的生产环境边界情况。

适合的目标群体

• 后端/API 架构师：负责设计或重构 API 版本策略的技术决策者。
• 全栈开发者：需要理解何时以及如何安全地推出 API 新版本的一线开发人员。
• API 产品经理：需要把握版本兼容性对第三方消费者影响的产品或平台运营者。
• DevOps 工程师：负责通过 API 网关实现版本路由和废弃版本服务下架的基础设施人员。

使用风险

1. 内容准确性与时效性风险：来自个人维护的 T3 来源，文档可能未及时随技术趋势更新，或包含主观性较强的观点。使用前建议与其他权威源（如 Microsoft REST API Guidelines、Google API Improvement Proposals）交叉验证。
2. 实施复杂性风险：文档中提出的多版本支持、适配器模式等架构，若在小型项目中过度实施，可能造成不必要的工程开销与维护负担。
3. 无运行时风险：由于 Skill 本身是纯文档，不存在注入攻击、恶意依赖、数据泄露等直接安全风险。唯一的合规风险是缺失许可证，可能导致后续的法律用途不明确。

安全性检查报告将此 Skill 评为 A 级（T3 来源上限），安全分 97 分，确认其无任何恶意行为或敏感信息泄露。建议在使用前由数据负责人进行一次人工审查以确认内容与团队实践匹配，并补充开源许可证。