程序员如何做「API 版本控制」：不是改着玩，是向前兼容

API 一旦发布，就不能随便改。

但业务在变，API 也需要升级。怎么版本控制？

---

一、为什么需要 API 版本控制

1. 向前兼容

旧客户端还能用新 API。

2. 灰度发布

新版本可以逐步放量。

3. 多版本并存

不同版本的客户端，对应不同的服务端实现。

4. 追溯问题

出问题了，知道是哪个版本的 API 的问题。

---

二、版本控制的方式

1. URL 路径（最常用）

/api/v1/users
/api/v2/users

优点：直观，容易调试 缺点：URL 会变

2. Header

Accept: application/vnd.api+json; version=1

优点：URL 不变 缺点：不直观，需要额外配置

3. Query 参数

/api/users?version=1

优点：简单 缺点：容易忽略，影响缓存

---

三、版本升级的策略

1. 不破坏性修改

• 新增字段（不删除旧字段）
• 新增 API（不修改旧 API）
• 字段类型不改变

2. 破坏性修改

• 删除字段
• 修改字段类型
• 修改必需参数

破坏性修改必须升版本。

3. 废弃（Deprecation）

标记为废弃但还能用：

{
  "deprecated": true,
  "sunsetDate": "2025-01-01",
  "message": "请使用 /api/v2/users"
}

---

四、版本控制的最佳实践

1. 最小版本号

从 v1 开始，不要 v0。

2. 主要版本和次要版本

• 主要版本：不兼容的改动
• 次要版本：向后兼容的新功能

3. 维护多个版本

不要只维护最新版本，保留最近 2 个版本。

4. 文档清晰

每个版本有对应的文档。

5. 主动通知

废弃前通知调用方，给足够的迁移时间。

---

五、版本控制的工具

1. Swagger / OpenAPI

API 文档工具，支持多版本。

2. Postman

API 测试工具，支持环境切换。

3. API Gateway

nginx / Kong / Apigee，支持版本路由。

---

六、一句话总结

API 版本控制 = URL/Header/Query 参数 + 破坏性修改升版本 + 维护最近2个版本 + 文档清晰。