API Versioning
API 版本管理
API 版本管理是一套命名、修改、支持和淘汰 API 契约的计划，目的是避免破坏客户端。没有任何一种 URL 或响应头写法适用于所有 API。
另一个例子
薪资 API 发布 OpenAPI 契约 `2026-07`，同时让 `/v1` 客户端继续工作。新增可选字段不会破坏兼容性；但把 `netPay` 从整数分改成小数，就需要新的主版本契约、迁移示例、弃用响应头、使用数据和退役日期。
主要部分
- 01契约标识符
- 02兼容规则
- 03弃用与迁移
什么时候用
先定义兼容规则、变更类型、版本发现方式、支持期限和弃用政策，再选择路径、媒体格式或响应头写法。
什么时候不要用
不要每次发布都建立新的 API 版本。没有使用数据和旧版退役机制时，也不要承诺永久兼容。
代码里的名称
explicit compatibility policy + versioned OpenAPI document + deprecation and sunset lifecycle 上线前要检查
检查接口约定、任何情况下都不能破坏的规则、授权与输入限制。测试重试、重复执行只生效一次、超时与部分失败。验证数据完整性、兼容性、监控、恢复与回到上一版。
预期结果：为这套系统设计或检查 API 版本管理 (API Versioning)，并让数据保持正确、安全且容易维护。 用户场景：薪资 API 发布 OpenAPI 契约 `2026-07`，同时让 `/v1` 客户端继续工作。新增可选字段不会破坏兼容性；但把 `netPay` 从整数分改成小数，就需要新的主版本契约、迁移示例、弃用响应头、使用数据和退役日期。 技术概念或控制措施：API 版本管理 (API Versioning)。 适用理由：先定义兼容规则、变更类型、版本发现方式、支持期限和弃用政策，再选择路径、媒体格式或响应头写法。 不应使用的情况：不要每次发布都建立新的 API 版本。没有使用数据和旧版退役机制时，也不要承诺永久兼容。 工程要求：定义输入、输出、接口约定，以及任何情况下都不能破坏的规则。说明授权与输入检查范围。定义失败、超时、重试和重复执行只生效一次的规则。也要定义数据迁移与兼容限制。 运营要求：加入监控信号与隐藏敏感数据的日志。设置容量上限并写好操作手册。测试恢复与回到上一版的流程。 验收标准：接口约定与失败路径测试通过。重试或部分失败时，数据与授权规则仍正确。性能上限、监控、恢复与回到上一版的方法都已验证。 证据与限制（证据边界）：没有一份官方标准能涵盖全部内容。不同团队、平台或框架的用法可能不同。 待确认：程序运行环境、数据位置、流量形态、数据一致需求和安全边界。也要确认兼容周期、服务目标（SLO）与恢复上一版的限制。
检查这份需求
请 AI 编程助手检查当前如何使用 API 版本管理 (API Versioning)。 定义：API 版本管理是一套命名、修改、支持和淘汰 API 契约的计划，目的是避免破坏客户端。没有任何一种 URL 或响应头写法适用于所有 API。 生产环境检查：检查接口约定、任何情况下都不能破坏的规则、授权与输入限制。测试重试、重复执行只生效一次、超时与部分失败。验证数据完整性、兼容性、监控、恢复与回到上一版。 修改程序前，先列出看到的证据、缺口、严重程度，以及最小且安全的修正。