api-versioning

API Versioning Skill — API 版本控制

何时使用

• 设计公开 API（SDK / 第三方集成）
• 想做 breaking change 但有存量客户
• 内部服务 (microservices) 间接口演进
• 评审 PR 是否 breaking change
• 制定 deprecation 流程

一、版本载体四种

1. URL Path（最常见）

GET /v1/users/123
GET /v2/users/123

优点：直观 / 缓存友好 / curl 易测 / 多版本并存简单 缺点：版本号"侵入" URL（看似资源是不同的）

2. Header

GET /users/123
Accept: application/vnd.example.v2+json
# 或自定义
X-API-Version: 2

优点：URL 干净 / 资源同一 缺点：浏览器不能直接打开 / 缓存键需 Vary 头

3. Media Type

GET /users/123
Accept: application/vnd.example.user.v2+json

GitHub API v3 用法。学院派，实践少见（开发心智成本高）。

4. Query Param

GET /users/123?version=2

不推荐 —— 不像版本，像参数。

5. Date-based（Stripe / GitHub GraphQL）

Stripe-Version: 2026-04-15

每次 breaking change 发版日期 stamp，旧客户端永远拿到当时的语义。最强但最贵：服务端要长期维护多个 schema 版本。

二、Breaking vs Additive Change

Additive（向后兼容，不需要新版本）

• ✅ 加新 endpoint
• ✅ 加新 optional 字段（请求 / 响应）
• ✅ 加新 enum 值（前提：客户端容忍未知值）
• ✅ 放宽校验（要求 ≥ 18 → ≥ 0）
• ✅ 加新 HTTP method 在已有 path

Breaking（必须升版本）

• ❌ 删字段 / 改字段名
• ❌ 改字段类型
• ❌ 加 required 字段
• ❌ 改默认值（行为改变）
• ❌ 删 enum 值
• ❌ 改 HTTP 状态码语义
• ❌ 收紧校验（≥ 0 → ≥ 1）
• ❌ 改错误格式
• ❌ 改分页 / 默认排序

陷阱：加 enum 值表面 additive，但若旧 SDK 用 switch 没 default，会崩。枚举默认 breaking，除非协议要求"未知值视为 X"。

三、SemVer 在 API 上的应用

v1.2.3
↑ ↑ ↑
│ │ └─ patch: bug fix（永不 breaking）
│ └─── minor: 加功能（永不 breaking）
└───── major: breaking change

API URL 一般只暴露 major（/v1/）。minor / patch 透明升级。

四、Deprecation 流程（业界标杆）

1. 公告期（≥ 3 月）

• 发布 changelog
• 邮件 / dashboard 通知用户
• API 响应加 header：

Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Deprecation: true
Link: <https://api.example.com/v3/users>; rel="successor-version"
Warning: 299 - "v1 deprecated, use v3 by 2026-12-31"

2. 监控期

观察使用量下降曲线 / 联系大客户

3. 关闭期

• 返 410 Gone（不是 404）
• body 给迁移指引

HTTP/1.1 410 Gone
Content-Type: application/problem+json

{
  "type": "/errors/api-version-sunset",
  "title": "API v1 has been sunset",
  "detail": "Migrate to v3. See https://api.example.com/migration/v1-to-v3",
  "successor": "/v3/users"
}