为什么需要

API 一旦被外部客户端使用，就不能随意改动——因为改了会破坏调用方。

但业务在演进，接口必须变化。因此需要版本管理。

三种常见方式

一、URL 路径版本

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

优点：直观、易于理解和调试；可以在网关层做路由；不同版本可以独立部署。

缺点：URL 中引入版本号，与"资源 URI 应该稳定"的 REST 理念有张力；版本多了以后维护成本高。

这是最常见的方式。

二、请求头版本

GET /api/users
Accept: application/vnd.company.v2+json

或者自定义头：

X-API-Version: 2

优点：URL 保持稳定；可以在内容协商的框架下处理。

缺点：不够直观，调试时需要在请求头里加东西；客户端实现稍复杂。

三、查询参数版本

/api/users?version=2

优点：实现简单。

缺点：污染查询参数；不够规范；容易与业务参数混淆。

兼容性优先于版本号

最重要的原则：版本升级应该是最后手段，而不是常规操作。

向后兼容的改动（不需要新版本）：

  • 新增可选的请求参数；
  • 新增响应字段（客户端应忽略未知字段）；
  • 新增新的接口端点；
  • 新增可选的请求头。

破坏性改动（需要新版本或慎重处理）：

  • 删除响应字段；
  • 改变字段类型或含义；
  • 把可选参数改成必填；
  • 改变错误码的语义；
  • 改变认证方式。

实践建议：

一、客户端遵循"宽容原则"——忽略不认识的响应字段，这样服务端才能安全地新增字段。

二、服务端谨慎删除字段——先标记为 deprecated，给足迁移期，在监控确认无人使用后再移除。

弃用流程

一个规范的做法：

  1. 公告：通过文档、邮件、响应头告知。
Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT

（Deprecation 和 Sunset 是正在标准化的 HTTP 响应头，用于告知 API 的弃用状态和时间。）

  1. 监控：统计旧版本的使用量和调用方。
  2. 迁移支持：提供迁移文档，必要时主动联系大客户。
  3. 宽限期：通常 6–12 个月。
  4. 下线。

一个务实策略

内部 API：如果所有调用方都在自己控制范围内（如同一个组织内的几个服务），可以不用版本号，直接协调改动——版本管理的成本可能高于收益。

对外 API：必须认真做版本管理和兼容性。

灰度发布 + 双写：重大变更前，可以让新旧版本并行运行一段时间，通过监控确认新版本正常后再切换。

文档

版本管理与文档密不可分。每个版本都应该有：

  • 清晰的接口文档；
  • 变更日志（Changelog）；
  • 迁移指南（从 v1 到 v2 要改什么）。

OpenAPI（原 Swagger）是目前最主流 API 描述规范，支持自动生成文档和客户端代码。

说明：本文为 API 设计的知识整理。