2017年8月，Stripe 发布了一篇博客文章，详细阐述了他们如何通过「日期滚动版本」策略，在六年时间里完成了近百次向后不兼容的升级，同时保持与每个版本的完全兼容。这篇名为《APIs as infrastructure: future-proofing Stripe with versioning》的文章，至今仍被视为 API 版本控制的标杆实践。

但有趣的是，当 GitHub 在 2022 年 11 月推出自己的版本控制机制时，他们选择了完全不同的路径——同样是日期命名，但通过自定义 Header 传递版本信息。而 Facebook 的 Graph API 则采用了两年的固定生命周期策略。

为什么这些顶级公司没有统一的「最佳实践」？因为 API 版本控制本质上是一个权衡问题——在客户端稳定性、开发效率、维护成本和迁移压力之间寻找平衡。没有万能的方案，只有在特定场景下最合适的取舍。

版本控制的三种核心策略

URL 路径版本控制：最直观但代价高昂

这是最常见的方案：/api/v1/users、/api/v2/users。X/Twitter API 采用的就是这种模式，目前同时运行着 v2（当前版本）和 v1.1（遗留版本）。

优势显而易见：浏览器地址栏可见、调试方便、支持多版本并行运行。对于刚起步的团队，这是最快能跑起来的方案。

但问题在于「v1 永远不死」。一位开发者在生产事故复盘中写道：「我们原计划只保留 v1 几个月，结果两年后它还在那里，承载着惊人的流量。废弃旧版本是一个项目，不是一个开关。」

这种方案的隐性成本是技术债务的累积。每个版本都是一整套独立维护的代码路径，当 v1、v2、v3 共存时，开发团队需要同时理解三套行为差异。

Header 版本控制：干净但隐形的陷阱

Stripe 和 GitHub 都选择了 Header 方案，但细节不同：

# Stripe 方式
Stripe-Version: 2023-10-16

# GitHub 方式  
X-GitHub-Api-Version: 2022-11-28

Stripe 的方案最为精巧。首次调用时，账户自动绑定到当时最新的版本，后续所有请求都隐式使用该版本。开发者可以在 Dashboard 中升级固定版本，或通过 Header 覆盖单次请求的版本。

这种「账户级版本固定」机制解决了两个痛点：客户端不会意外收到破坏性变更；升级时机完全由客户端控制。

但 Header 方案有一个致命的陷阱——不可见性。一位工程师分享过真实案例：「团队的 Postman 集合没有设置 Header，所以他们以为 API 坏了。这种隐形机制被遗漏的频率令人惊讶。」

更麻烦的是，某些代理和工具会剥离自定义 Header。当请求经过企业防火墙或 CDN 时，版本信息可能「神秘消失」，导致调试变得极其困难。

内容协商版本控制：REST 理想主义者的选择

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

这是最「RESTful」的方案，将版本控制视为资源表示的一部分。GitHub 曾经长期使用这种模式。

理论上，它保持了 URL 的稳定性，将版本选择权完全交给客户端。但实践中，它要求客户端开发者对 HTTP 协议有相当程度的理解。对于大多数团队，这种方案的沟通成本过高。

破坏性变更的定义：比你想象的更窄

理解什么是「破坏性变更」是版本控制的前提。GitHub 的文档给出了明确的定义：

破坏性变更包括：

  • 删除整个操作
  • 删除或重命名参数
  • 删除或重命名响应字段
  • 添加新的必填参数
  • 将可选参数变为必填
  • 改变参数或响应字段的类型
  • 删除枚举值
  • 添加新的验证规则
  • 改变认证或授权要求

非破坏性变更包括：

  • 添加新操作
  • 添加可选参数
  • 添加可选请求头
  • 添加响应字段
  • 添加响应头
  • 添加枚举值

这个定义的关键洞见是：添加内容通常不是破坏性的。这引出了 API 演进的核心原则——尽可能只添加，不删除。

大厂策略对比：不同的权衡

Stripe：滚动迁移层

Stripe 的实现堪称工程典范。每个破坏性变更被封装在「版本变更模块」中，定义了变更文档、数据转换逻辑和受影响的资源类型。

# 伪代码示意
version_changes = [
  { version: '2014-01-31', transform: convert_verified_to_status },
  { version: '2014-03-13', transform: add_idempotency_key_to_event }
]

当生成响应时，API 首先按最新版本格式化数据，然后根据请求的目标版本，逆向遍历并应用每个版本变更模块，直到达到目标版本。

这种设计的精妙之处在于：核心代码路径不需要关心历史版本。开发者构建新功能时，只需考虑最新的数据结构。旧版本的兼容逻辑被完全隔离在转换层中。

但这种方案的实施成本极高。Stripe 维护了超过 100 个版本变更模块，每个模块都是额外的代码需要理解和测试。只有当 API 是核心业务基础设施时，这种投入才值得。

GitHub：日期版本 + Header

GitHub 在 2022 年 11 月推出了 X-GitHub-Api-Version 机制，同样采用日期命名（2022-11-28）。他们的承诺是：当新版本发布时，旧版本至少继续支持 24 个月。

这与 Facebook 的策略形成对比。Facebook Graph API 明确规定：每个版本保证运行至少两年，从下一版本发布之日算起。例如，如果 v2.3 在 2015 年 3 月发布，v2.4 在 2015 年 8 月发布，那么 v2.3 将在 2017 年 8 月过期。

时间确定性是这些方案的核心价值。客户端开发者可以精确规划升级时间线，而不是面对「随时可能下线」的不确定性。

Facebook：版本生命周期管理

Facebook 的策略最为激进。当未指定版本的请求到达时，系统会使用应用仪表板中设置的「升级版本」。更关键的是，如果应用从未调用过某个版本，它将无法调用该版本。

这是一个「版本锁定」机制：应用创建后首次调用的版本，决定了它能访问的版本范围。新创建的应用无法调用比它创建时间更早的版本。

这种策略有效地避免了「僵尸客户端」问题——那些停留在古代版本的代码。但它也带来了迁移压力：如果你错过了某个版本的窗口期，就必须升级到最新版本。

版本废弃的标准做法：RFC 8594

2019 年 5 月，IETF 发布了 RFC 8594，定义了 Sunset HTTP 响应头字段。这是 API 废弃通知的标准方案：

HTTP/1.1 200 OK
Sunset: Sat, 31 Dec 2024 23:59:59 GMT
Link: <https://api.example.com/deprecation-policy>; rel="sunset"

Sunset 头指示资源将在指定时间点变得不可用。配合 Link 头的 sunset 关系类型，可以指向废弃策略文档。

关键点：Sunset 是一个「提示」，而非「保证」。RFC 明确指出，客户端应将其视为资源所有者提供的信息，但不应假设资源确实会按该时间下线。

Zalando 的 RESTful API 指南更进一步，推荐同时使用 Deprecation 头（RFC 9745，草案阶段）和 Sunset 头：

Deprecation: true
Sunset: Wed, 11 Nov 2026 11:11:11 GMT

Deprecation 头表明资源已被废弃，Sunset 头则指明具体的下线时间。

学术研究揭示的实践现状

2023 年，瑞士 USI 大学的研究者对 7,114 个 GitHub 上的 API 进行了大规模实证研究，揭示了版本控制的真实状况。

关键发现：

  1. 语义版本控制占据主导：在 info.version 字段中，60.56% 的 API 使用语义版本控制（SemVer），如 1.0.0。

  2. URL 中的版本标识更简洁：当版本标识嵌入 URL 路径时，最常见的格式是仅使用主版本号（如 v1、v2），而非完整的 1.0.0。

  3. 多版本并存并不罕见：135 个 API 在路径中包含多个版本标识。其中一个 API 在某些提交中同时支持多达 14 个版本。

  4. 版本格式不稳定：534 个 API 在其生命周期中切换了版本格式。最常见的转换是「无版本 → 语义版本控制」。

  5. 预发布标签多样：开发（dev）、快照（SNAPSHOT）、预览（preview）、alpha、beta、候选版本（RC）等标签在 25,308 个提交中出现，涉及 535 个 API。

这项研究最重要的结论是：没有单一标准。即使语义版本控制被广泛推荐，实践中仍存在大量变体和例外。

GraphQL 和 gRPC 的不同哲学

GraphQL：版本控制是反模式

GraphQL 官方文档明确表态：「GraphQL 强烈反对版本控制，提供持续演进 Schema 的工具。」

核心理念是：由于客户端只请求显式指定的字段，添加新字段永远不会是破坏性变更。因此，GraphQL 倡导通过以下方式演进 API：

type User {
  id: ID!
  name: String!
  email: String @deprecated(reason: "Use 'emails' for multi-email support")
  emails: [Email!]!
}

@deprecated 指令允许标记即将移除的字段，客户端有充足时间迁移。这本质上是将版本控制从「API 级别」下沉到「字段级别」。

但 GraphQL 无法避免所有破坏性变更。当必须删除字段或改变类型时，唯一的方案是让客户端更新——这又回到了通知、迁移、废弃的传统流程。

gRPC：协议层面的兼容性保证

gRPC 和 Protocol Buffers 提供了比 REST 更强的兼容性保证。Microsoft 的文档明确列出了非破坏性变更：

  • 添加新服务
  • 向服务添加新方法
  • 向请求消息添加字段（服务端用默认值处理）
  • 向响应消息添加字段（客户端忽略未知字段）
  • 向枚举添加值（客户端看到数值而非名称）

关键机制是 字段编号。Protocol Buffers 使用数字而非名称标识字段：

message User {
  string name = 1;  // 字段编号 1
  int32 age = 2;    // 字段编号 2
}

即使重命名字段，只要字段编号不变，二进制格式仍然兼容。这比 JSON 的基于字段名方案更加健壮。

但 gRPC 同样有破坏性变更：改变字段编号、改变字段数据类型、删除服务或方法、重命名包/服务/方法。当这些变更不可避免时，推荐的做法是在包名中嵌入版本号：

package myservice.v1;
service MyService { ... }

package myservice.v2;
service MyService { ... }

生产事故的教训

版本控制的失败往往不是技术问题，而是流程问题。

事故一：CDN 缓存混乱

一个团队使用查询参数版本控制（/api/users?version=2）。由于 CDN 配置错误，缓存响应时没有考虑版本参数。结果是：v2 客户端收到了 v1 的数据。

这种问题的根源是版本信息的「地位」不明确。URL 路径版本控制天然被缓存系统识别为不同资源，而查询参数和 Header 则需要额外配置。

事故二：Header 被剥离

某企业 API 使用自定义 Header 传递版本。当请求经过公司防火墙时，Header 被「安全策略」移除。API 服务端收到请求后，使用了默认版本，返回了与客户端预期不符的数据结构。

教训：依赖 Header 的方案必须在网络层面端到端验证，任何中间层都可能成为故障点。

事故三：方法级版本控制的混乱

一个极端案例是「方法级版本控制」：GET /api/v2/users 存在，但 POST /api/v3/users 是最新版本，而 GET /api/v3/users 根本不存在。

这种设计导致客户端被迫混用多个版本号，认知负担极高。更糟的是，当新的更新方法只包含旧方法的部分功能时，客户端即使想迁移也无法完成。

选择策略的决策框架

没有放之四海皆准的方案，但可以通过以下维度评估：

1. 客户端类型

内部 API：Header 或内容协商方案可行，因为可以强制要求客户端配合。如果后端团队和前端团队沟通紧密，甚至可以考虑「不版本控制」的演进策略。

公开 API：URL 路径版本控制最安全。它对客户端技术栈无要求，任何 HTTP 客户端都能轻松使用。当你不知道客户端是谁时，最简单的方案往往最可靠。

2. 变更频率

高频小变更：考虑 Stripe 的滚动迁移层方案。每次变更的迁移成本很低，客户端可以按自己的节奏升级。

低频大变更：全局版本控制（v1/v2）可能更合适。既然变更很少，每次大版本升级的成本分摊到时间线上是可接受的。

3. 客户端数量

少数已知客户端：可以依赖直接沟通。版本控制机制可以简单，甚至可以省略自动化的废弃通知。

大量未知客户端：必须依赖标准化机制（RFC 8594 Sunset 头）和超长的支持周期。Facebook 的两年保证就是这种场景的典型策略。

4. API 重要性

核心基础设施：投入资源构建 Stripe 级别的迁移层。API 的稳定性直接影响业务收入，值得工程投入。

辅助工具：简单方案足够。一个内部管理后台的 API 不需要复杂的版本控制。

实施检查清单

无论选择哪种策略，以下实践能够显著降低风险：

版本发布前

  • 是否有破坏性变更？如有，是否真的必要？
  • 能否用新增字段代替修改现有字段？
  • 所有破坏性变更是否已记录在变更日志中？

版本运行中

  • 是否监控每个版本的调用量？
  • 是否有版本废弃的时间线？
  • 是否已设置 Sunset 响应头？
  • 文档是否已更新，标注废弃字段？

版本废弃时

  • 是否提前通知了所有已知客户端？
  • 是否有足够长的过渡期（建议至少 6-12 个月）？
  • 是否提供了迁移指南？
  • 是否有强制升级的机制（如返回警告响应）？

结语

API 版本控制的本质是一种契约管理。API 一旦发布，就与客户端建立了隐式契约。版本控制机制的本质，是让这份契约可以安全地演进。

Stripe 的方案最优雅，但实施成本最高；URL 路径方案最简单，但维护成本随版本累积；Header 方案最干净，但调试成本最高。

选择的关键不在于「哪个最好」，而在于「哪个最适合你的场景」。当你理解了每种方案背后的权衡，才能做出知情的选择。

最后，无论选择哪种方案，记住一条原则：版本控制是最后的手段，兼容性演进才是首选。当你发现自己频繁需要版本控制时，问题可能不在版本控制机制本身，而在 API 设计的合理性上。

参考资料

  • Stripe Blog. APIs as infrastructure: future-proofing Stripe with versioning. 2017.
  • GitHub Docs. API Versions. 2022.
  • Meta Developers. Platform Versioning.
  • X Developer Platform. Versioning.
  • Wilde, E. RFC 8594: The Sunset HTTP Header Field. IETF, 2019.
  • Serbout, S. & Pautasso, C. An empirical study of Web API versioning practices. ICWE 2023.
  • GraphQL. Schema Design.
  • Microsoft Learn. Versioning gRPC services.
  • Zalando. RESTful API Guidelines: Deprecation.
  • APIs You Won’t Hate. API Versioning Has No Right Way.