本指南系统整理了 API 版本管理相关的策略与实践，按主题分为若干部分。
一、用途 该资料用于帮助设计、维护和演进 API 的版本策略，重点解决版本标识方式选择、向后兼容控制、弃用流程安排以及版本生命周期协调等问题，适用于需要向外部或内部消费者长期提供 API 的工程场景。
二、主要能力
- 版本化方案：介绍 URL 路径版本（如 /api/v1/users）、请求头版本（Accept 内容协商或 X-API-Version 自定义头）、查询参数版本（?version=2）三种方式，并分别列出优点、缺点与适用场景，附带 Stripe、GitHub、Google Cloud 等实际案例。
- 语义化版本：说明 MAJOR.MINOR.PATCH 在 API 中的含义；URL 版本化通常只在路径中体现 MAJOR，MINOR 与 PATCH 通过变更日志或响应头传达。
- 变更分类：区分破坏性变更（如删除或重命名字段、改变字段类型、删除端点、把可选字段变为必填、改变认证、错误格式或分页结构）与非破坏性变更（新增可选字段、端点、查询参数、放宽校验等），并指出灰色地带。
- 弃用策略：使用 RFC 8594 的 Sunset 响应头配合 Deprecation 头与迁移链接，在 OpenAPI 中标注 deprecated，记录弃用端点调用量，并提供典型时间线（从公告到移除约 12 个月，公共 API 可能需 18-24 个月）。
- 生命周期管理：定义预览、活跃、弃用、退役四种状态，建议同时保持不超过 2-3 个活跃大版本，并讨论省略版本号时的默认行为选择。
- 变更日志：给出结构化、机器可读的 JSON 变更日志示例，分类为 added、changed、deprecated、removed、fixed、security。
- 兼容模式：仅做增量变更、可选字段带默认值、保持响应信封结构稳定、倡导宽容读取器模式（消费者忽略未知字段、不依赖字段顺序、优雅处理缺失可选字段）。
- 数据库模式版本化：扩展-收缩、版本化视图、迁移排序等策略，强调在旧版本仍读取某列时不得删除该列，用特性开关控制写入，并测试回滚场景。
- OpenAPI 版本管理：按大版本维护独立规格文件，在 CI 中用 oasdiff 或 openapi-diff 自动检测破坏性变更。
- 实际示例：给出 REST 端点演进与 GraphQL 模式增量演进的代码示例，并列举常见错误（过早版本化、活跃版本过多、版本方式不一致、把小改动当作大版本、缺少版本发现机制）。
- 迁移工具与沟通：消费者代码自动改写脚本、适配层、带升级说明的版本化 SDK、沙箱环境，以及变更日志邮件、开发者门户公告、使用看板、针对高流量消费者的直接联系，并通过监控旧版本流量占比来决策退役。
三、使用方式 资料以方法说明、对比、代码片段与清单形式呈现，可用于评审 API 设计、制定弃用时间表和编写迁移文档。文末列出 RFC 8594、语义化版本规范、OpenAPI 规范、Stripe 与 GitHub 版本化文档、Google Cloud API 设计指南等参考。
四、适用场景与限制 适用于 REST 与 GraphQL API 的版本规划、兼容性治理、弃用与退役协调。资料未提供该技能的具体安装命令、运行环境或工具集成方式，暂未提供。