القائمة
设计 API 版本管理和兼容变更策略时使用。适用于公开 API、SDK、长期维护项目。优先使用 Stripe 版本策略 + 兼容/不兼容变更分类 + 弃用流程。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | versioning |
| description | 设计 API 版本管理和兼容变更策略时使用。适用于公开 API、SDK、长期维护项目。优先使用 Stripe 版本策略 + 兼容/不兼容变更分类 + 弃用流程。 |
参考来源：Stripe API Versioning、Semver 思想
1. 兼容变更优先
能不升版本就不升
2. 不兼容变更必须升版本
不能悄悄改
3. 老版本要有弃用期
不能立即下线
4. 版本策略全 API 统一
不要不同模块用不同方式
不需要升版本的变更：
✅ 新增可选字段（请求和响应）
✅ 新增端点
✅ 新增可选参数
✅ 新增错误码
✅ 新增枚举值（响应中，调用方应忽略未知值）
✅ 放宽校验（如：原 max=10 改为 max=20）
✅ 新增 HTTP 方法（如原只支持 GET，新增 POST）
必须升版本的变更：
❌ 删除字段
❌ 删除端点
❌ 重命名字段
❌ 改字段类型（string → integer）
❌ 改字段语义（同名字段含义变了）
❌ 改必填规则（可选 → 必填）
❌ 改默认值
❌ 改枚举值含义（仅添加是兼容的，删除/重命名不兼容）
❌ 改错误响应结构
❌ 改 HTTP 状态码（200 → 201）
❌ 改鉴权方式
❌ 收紧校验（max=20 改为 max=10）
❌ 改分页风格（offset → cursor）
/api/v1/users
/api/v2/users
优点：
✅ 直观
✅ 缓存友好
✅ 易于路由
缺点：
❌ 升级时所有 URL 都变
❌ 一个端点的小变更也要全升
Accept: application/vnd.example.v2+json
或自定义：
X-API-Version: 2
优点：
✅ URL 干净
✅ 可按端点细粒度版本
缺点：
❌ 不直观
❌ 缓存配置复杂
❌ 浏览器测试不方便
Stripe-Version: 2024-01-15
优点：
✅ 精确到日期
✅ 客户端可固定版本
✅ 升级路径清晰
缺点：
❌ 维护成本高（每个变更都是新版本）
Accept: application/json; version=2
优点：
✅ 符合 REST 原则
缺点：
❌ 复杂
❌ 多数客户端不熟悉
内部 API → 不需要版本（前后端同步）
公开 API（普通） → URL 版本 (/v1, /v2)
公开 API（精细） → 日期版本（Stripe 风格）
开放平台（成熟） → URL 版本 + 日期细化
1. 公告（Announce）
- 提前 6~12 个月通告
- 邮件 / 文档 / Changelog
- 提供迁移指南
2. 标注（Deprecate）
- 响应 Header：Sunset: <date>
- 文档明确标注 deprecated
- 提供新端点 / 新字段
3. 警告（Warn）
- 响应 Header：Deprecation: <date>
- 日志记录使用情况
- 联系大客户
4. 下线（Sunset）
- 到期下线
- 老调用返回 410 Gone
- 错误信息指向新版本
时间表示例：
Day 0：发布 v2，v1 标 deprecated
Day 90：v1 警告（响应 header）
Day 180：v1 错误（部分非关键端点）
Day 365：v1 完全下线
旧 v1：
GET /users/{id}
{
"id": "usr_001",
"name": "张三"
}
新 v1（新增字段，兼容）：
GET /users/{id}
{
"id": "usr_001",
"name": "张三",
"email": "user@example.com", ← 新增
"phone": "+86138..." ← 新增
}
老客户端忽略未知字段，不影响
旧 v1：
{
"user_id": "usr_001", ← 旧字段名
"user_name": "张三"
}
新 v2：
{
"id": "usr_001", ← 重命名
"name": "张三"
}
必须 /v2/users/{id}
v1 保留过渡期
## 版本变更评估：[变更内容]
### 变更描述
[具体改了什么]
### 兼容性评估
- 变更类型：兼容 / 不兼容
- 受影响的字段/端点：
- 受影响的客户端：
### 兼容判断
- [ ] 是否新增字段（兼容）
- [ ] 是否新增端点（兼容）
- [ ] 是否删除字段（不兼容）
- [ ] 是否改字段类型（不兼容）
- [ ] 是否改语义（不兼容）
- [ ] 是否改必填（不兼容）
### 决策
- ✅ 兼容变更，无需升版
- ❌ 不兼容变更，需要 v2
### 如果升版
- 新版本号：v2
- 老版本弃用期：6 个月
- 迁移指南：[链接]
- 通知方式：邮件 + Changelog
paths:
/v1/users:
get:
summary: List users (deprecated)
deprecated: true
description: |
This endpoint is deprecated and will be removed on 2026-12-31.
Please use /v2/users instead.
Migration guide: https://docs.example.com/migration/v2
1. 评估变更是否兼容（用上方评估模板）
2. 如果兼容 → 直接修改，更新文档
3. 如果不兼容 → 决定升版策略
4. 创建新版本，老版本保留
5. 写迁移指南
6. 发布弃用公告
7. 监控老版本使用率
8. 到期下线
□ 是否区分了兼容和不兼容变更
□ 兼容变更是否真的兼容（不要侥幸）
□ 不兼容变更是否升了版本
□ 弃用是否有充足时间（≥ 6 个月）
□ 是否有迁移指南
□ 是否在 OpenAPI 标注 deprecated
□ 是否监控老版本使用率
templates/api-version-change-template.md — 变更评估 + 迁移指南 + 弃用公告模板上游：
product-manager 的需求变更
平行：
endpoint-design → 新版本端点设计
request-response → 字段变更评估
error-handling → 错误码版本兼容
下游：
openapi-mock → 多版本 OpenAPI
转交技术文档 → 迁移指南
设计 API 认证鉴权和权限矩阵时使用。适用于多角色系统、租户隔离、字段级权限。优先使用 OAuth 2.0 / JWT + RBAC + 资源归属检查。
设计具体 API 端点时使用。适用于资源建模后的下一步、列端点清单、HTTP 方法和状态码选择。优先使用 RFC 7231 HTTP 语义 + GitHub REST 命名规范。
设计 API 错误码和错误结构时使用。适用于错误响应规范、调用方错误处理、调试可观测。优先使用 RFC 7807 Problem Details + 业务错误码 + 调用方处理建议。
设计幂等接口和重试策略时使用。适用于支付、扣减、订单、关键写操作。优先使用 Idempotency-Key + 业务去重键 + 并发冲突处理（ETag/版本号）。
输出 OpenAPI 契约和 Mock 服务时使用。适用于 API 设计的最后一步、给前端/后端/QA 的交付。优先使用 OpenAPI 3.1 + Mock 数据覆盖所有路径 + 详细的下游交接清单。
设计列表接口的分页、筛选、排序、搜索时使用。适用于所有列表 API。优先使用 cursor 分页（大数据）或 offset 分页（小数据）+ 统一筛选/排序规范。