Menu
设计 API 版本管理和兼容变更策略时使用。适用于公开 API、SDK、长期维护项目。优先使用 Stripe 版本策略 + 兼容/不兼容变更分类 + 弃用流程。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
设计 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 分页（小数据）+ 统一筛选/排序规范。
| 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
转交技术文档 → 迁移指南