2. API 版本控制策略

API 版本控制是弃用迁移的基石。没有清晰的版本标识，客户端无法区分当前调用的是稳定接口还是即将下线的旧接口，自动化回滚也无法精准定位目标版本。本节从四种主流控制方式入手，分析其适用场景与兼容性设计原则。

2.1 四种版本控制方式对比

2.2 URI 版本控制详解

将版本号直接嵌入 URL 路径，是最早被广泛采用的方式。RESTful 风格下，版本号通常放在 API 前缀之后、资源路径之前。

# 示例：URI 版本控制
GET /api/v1/users/123
GET /api/v2/users/123
POST /api/v2/orders

优点：

• 客户端一眼可知版本，无需解析 Header。
• CDN 和反向代理可直接按路径缓存，版本隔离天然。
• 路由配置简单，Nginx / API Gateway 可轻松分流。

缺点：

• 版本与资源绑定过紧，同一资源可能同时存在 /v1/users 和 /v2/users，造成 URL 膨胀。
• 语义上版本应属于协议层而非资源标识，部分 REST 纯粹主义者反对此方式。

2.3 请求头版本控制详解

通过自定义 HTTP 请求头或 Accept 头中的媒体类型参数传递版本信息。这种方式将版本从 URL 中剥离，使资源路径保持稳定。

# 示例：自定义头方式
GET /api/users/123
X-API-Version: 2

# 示例：Accept 头内容协商方式
GET /api/users/123
Accept: application/vnd.mycompany.v2+json

优点：

• URL 干净，资源标识不受版本干扰。
• 支持细粒度内容协商，同一资源可返回不同格式。

缺点：

• 浏览器直接测试困难，需借助 curl / Postman 等工具。
• CDN 缓存默认不识别自定义头，需额外配置 Vary 头，可能降低缓存命中率。

2.4 参数版本控制详解

在查询字符串（Query String）中携带版本参数。实现成本最低，适合快速原型或过渡方案。

# 示例：参数版本控制
GET /api/users?version=2
GET /api/orders?version=1&status=active

优点：

• 后端实现简单，只需解析参数即可路由。
• 客户端无需修改 URL 路径或 Header。

缺点：

• 参数与业务参数混在一起，容易造成冲突或遗漏。
• 缓存键需包含 version 参数，否则不同版本可能返回错误结果。
• URL 语义不清晰，版本信息容易被忽略。

2.5 版本兼容性设计原则

无论采用哪种控制方式，版本兼容性设计决定了弃用迁移的平滑程度。以下是三条核心原则：

1. 向后兼容（Backward Compatible）：新版本必须能处理旧版本的所有合法请求，不能删除或修改已有字段的语义。
2. 增量演进（Additive Only）：尽量只增加新字段、新端点，不改变已有字段的类型、约束或含义。
3. 弃用头（Deprecation Header）：在旧版本响应中加入 Deprecation: true 和 Sunset: Sat, 31 Dec 2025 23:59:59 GMT，让客户端提前感知。

# 兼容性设计示例：响应中的弃用头
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com"
  // v2 新增字段，v1 客户端忽略即可
  // "phone": "+86-13800138000"
}

2.6 版本控制策略选择矩阵

2.7 版本兼容性设计模式

在实际工程中，版本兼容性设计通常采用以下三种模式：

2.8 版本控制与自动化回滚的关联

版本控制策略直接影响回滚模板的设计决策：

• URI 版本控制：回滚时只需将 API Gateway 路由从 /v2/* 切回 /v1/*，无需修改客户端请求。
• 请求头版本控制：回滚需确保客户端发送的版本头被正确降级，可能涉及 SDK 或配置中心推送。
• 参数版本控制：回滚最复杂，需清理缓存中携带 version 参数的键值，否则旧版本可能被错误缓存。