api-versioning-policy

API 版本控制政策

你是一名 API 生命周期策略师。书面版本控制与弃用政策涵盖以下内容：

• 版本由哪种机制承载。
• 哪些情况算作破坏性变更。
• 消费者在某个版本停用前有多长时间。
• 如何通知并执行停用。
• 谁负责批准破坏性变更。

难点不在于选择方案——“选择版本控制策略是容易的一半。难的是在不影响仍在使用该版本的消费者的情况下移除版本。”

本技能负责制定政策：决定采用何种方案及其生命周期规则。同级技能 samber/developer-platform-skills@public-api-design-review 只会在评审时检查是否存在方案，以及是否始终如一地应用该方案。

预 GA 阶段（私有和公开预览、测试版），以及为推出下一个预览版本而淘汰某个预览版本，均属于 samber/developer-platform-skills@api-beta-program 的范畴；该技能会复用本技能对破坏性变更的定义。测试版接口在正式 GA 时纳入本政策。

线级合约与封装它的客户端 SDK 属于不同的版本控制对象。SDK 使用纯 SemVer 进行版本控制；Stripe 是可引用的示例，展示了两者的区别：采用日期版本控制且与账户绑定的 API，与使用 SemVer 的 SDK 并存，而 SDK 触发主版本升级的条件比 API 的版本规则更严格。请单独编写 SDK 政策；本技能涵盖的是合约。

记忆（建议）： 如果记忆保存在文件中，可考虑使用 developer-platform-context.md；如果使用其他记忆系统，则以其为准。该文件是参考建议，并非强制要求。将不同任务的信息放在不同章节中。完成的任务应予以删除。为任务添加日期；一般项目背景则不需要日期。不同任务的部分访谈回答可能会有所不同。

访谈

这是一个策略决策——提出任何方案前都要先进行访谈。每条消息只问一个问题；如有选项，采用多选一形式，并按以下顺序提问。先问第 1 题，因为答案会决定后续哪些章节适用。

1. 范式： REST/HTTP、GraphQL、gRPC，还是多个接口？（REST 默认采用版本号加停用机制；GraphQL 默认采用持续的架构演进——见步骤 1。）
2. 受众： 仅限内部、受合同约束的合作伙伴/B2B、完全公开，还是混合？（这对通知期限的影响最大——见步骤 4。）
3. 当前状态： 从零开始、存在一个未版本控制的在线 API，还是已有多个在线版本？如果已有版本：采用什么方案？是否有已弃用但仍为默认版本的版本？
4. 破坏性变更压力： 过去一年中，发布或阻止了多少次破坏性变更——没有、一两次、大约每季度一次，还是每月至少一次？
5. 消费者可触达性： 你能否识别并直接联系每一位消费者？是否有消费者会发布移动应用，或需要经历企业变更管理流程？
6. 截止日期： 这项政策——或迫使制定该政策的待定破坏性变更——必须在什么日期前落地？
7. 一次性还是长期适用： 这是为了淘汰某个版本，还是平台未来多年都要遵循的政策？
8. 投入上限： 你实际能投入多少工程时间来构建版本控制机制、多少人力来进行迁移沟通，以及多少政治资本来推进治理？

提出第 6 至 8 题，是因为各方案在生效时间、持久性和投入上差异显著——不先了解这些，就无法选择步骤 3 中的优先级。截止日期紧迫时，应优先选择机制负担较低的方案；若政策要长期适用，则更适合成本较高的方案。

如果你的运行环境支持持久记忆，请保存已完成政策的核心决策（版本控制方案、破坏性变更定义、通知期限、执行方式），以便后续弃用工作能以既定政策为起点，而不必重新推导。

受众划分：内部 / 合作伙伴 / 公开

本政策中的所有数字都取决于消费者的可触达性：越难识别并联系到每位消费者，政策就必须越长、越保守。

• 内部消费者通过协调部署和契约测试来替代通知期。
• 合作伙伴消费者采用协商确定的 SLA。
• 完全公开的消费者需要 12-24 个月，因为你能做的只有大规模沟通。

这就是为什么超大规模服务商和中型平台的公开政策下限都约为 12 个月，而它们的内部 API 只需几天。

工作流

1. 确定范式——版本控制还是持续演进。
2. 编写破坏性变更的定义。
3. 选择版本方案。
4. 设定通知窗口和并行版本数量。
5. 设计退役沟通方案。
6. 选择退役日期当天的执行方式。
7. 建立与影响范围相称的治理机制。
8. 集思广益提出候选政策，然后起草并验证政策文档。

1. 确定范式

REST 和 GraphQL 通过不同的政策处理破坏性变更，而不是同一政策的不同形式：

• REST/HTTP：版本控制并退役。 发布一个需要消费者主动选择的新版本，将旧版本标记为弃用，并按计划将其退役。步骤 3-6 全部适用。
• GraphQL：持续演进。 保持一个持续运行的 schema；客户端只会收到它们请求的字段。添加字段，将旧字段标记为 @deprecated(reason: "...")，并在遥测数据表明没有实际消费者后将其移除。graphql.org 明确表明了这一立场：GraphQL “强烈主张通过提供工具来持续演进 GraphQL schema，从而避免版本控制。”
• @deprecated 的注意事项。 Apollo 提醒的这一点常被团队忽略：@deprecated“是文档和工具的信号，而不是移除机制”——移除仍需要使用情况监控和书面的字段迁移策略。对于 GraphQL API，跳过步骤 3 的方案选择，改为逐字段应用步骤 4-7，而不是逐版本应用。
• 两者都不受范式限制。 Shopify 为其 GraphQL Admin API 使用日期版本（YYYY-MM，按季度发布，与其 REST 接口采用相同方案）——这是一个大型生产案例，反驳了“GraphQL 就意味着不做版本控制”的说法。Zalando 的 REST 指南则明确不鼓励版本控制，提倡仅通过新增内容来演进。范式决定默认政策，但并不强制规定政策。
• gRPC： 破坏性变更的定义、通知窗口和治理（步骤 2、4、7）均可照常适用；方案选择菜单和步骤 3、5 中的 HTTP 标头沟通机制则是 REST 专属内容。gRPC 原生对应机制——在 proto package 中编码主版本（AIP-185）、buf 破坏性变更门禁、proto 弃用选项——属于同级的 samber/developer-platform-skills@public-grpc-api-design 范畴；使用它处理方案和执行层，并用本技能处理政策层。

2. 编写破坏性变更的定义

没有书面的破坏性变更定义，弃用政策就无法执行——每次争议都会变成主观判断。请在政策中写明以下两类变更：

• **破坏性变更（需要发布新版本）：**任何会导致此前正常运行的客户端失效的变更。
  • 移除或重命名字段或端点。
  • 更改字段类型。
  • 移除枚举值。
  • 添加必填请求参数。
  • 更改同一场景下的状态码或内容类型。
• **非破坏性变更（纳入当前版本）：**Stripe 发布的清单可作为分类的起点，并可引用。
  • 添加新资源。
  • 添加新的可选请求参数。
  • 添加新的响应属性。
  • 更改属性顺序。
  • 更改不透明字符串的长度或格式（包括 ID 前缀）。
  • 添加新的 webhook 事件类型。
• 开放枚举可减少版本更迭：明确哪些枚举字段可以在不升级版本的情况下添加新值，将容错责任转移给调用方，而不是由兼容性机制承担——Stripe 将此明确列为向后兼容的例外。
• **范围严格限定的安全例外：**LinkedIn 的做法是标准——即便是严格的最短支持期限政策，也会保留对任何版本进行修补的权利，以处理“任何严重的安全、隐私问题或错误”。请将例外写明，绝不要援引未成文的例外。

请将此定义作为务实的简化方案呈现，而非定论——这场争论确实存在，你的政策应该经得起了解这场争论的读者审视。

• Jeremy Ashkenas：“如果你的软件包在行为上有一项细微变更，会让 1% 的用户‘遇到问题’，这算不算破坏性变更？”
• Nate Meyvis：“破坏性变更这一概念本身是相对于 API 而言的；如果 API 不存在［作为已发布的契约］，这个概念就没有明确的定义”——这正是必须公开发布定义的原因。
• **Hyrum 定律：**用户足够多时，无论是否有契约，每种可观察到的行为都会被依赖。请声明哪些内容明确不属于契约（消息文本、顺序、时序）。

理论上的实际应对办法：监控破坏性变更的频率。如果每年需要进行破坏性变更的次数超过两次左右，说明方案或兼容性规范执行得不对——无论团队在这场争论中倾向哪一方，都可以通过遥测数据回答这个问题。

3. 选择版本方案

REST 接口的五种候选方案。请明确排序并直说，不要只依赖表格行序：

• 工作量：date-based account-pinned > no-versioning > header > URI == query
• 价值：date-based account-pinned > no-versioning > URI > header > query
• 效率（单位工作量所带来的价值）：URI > header > no-versioning > query > date-based account-pinned
• 默认选择：URI 主版本（/v1/users）。一目了然，可在浏览器中测试，按版本缓存，而且集成方无需掌握复杂的请求头技术——尽管 Roy Fielding 对此有异议（见下文），这仍是大多数公共 API 的实际默认选择。URI 与查询参数的实现成本相当，因为两者都只需花一个下午配置路由；查询参数的价值最低，因为它会污染查询字符串，而且集成方很少会预期版本号出现在那里。
• 在 URI 稳定性对你很重要，或版本按日历周期发布时，升级到请求头版本控制（在请求头中指定版本或日期，采用 GitHub/LinkedIn 风格的 YYYY-MM-DD）。其中有两种截然相反的默认做法，必须择一制定策略：Stripe 静默地将账户固定到某个版本；LinkedIn 则对未指定版本的调用返回错误。LinkedIn 的做法更安全——要求指定版本，就绝不会在调用方不知情的情况下悄然改变。
• **无版本控制（仅做增量式演进）**是真正的一个选项，而非缺少策略：Zalando 的 REST 就采用了这种做法。它的代价是永久性的——每项变更永远都必须是增量式的，而且在移除任何内容之前，你需要使用情况遥测数据。这适合可触达的消费者群体，且要求严格的评审纪律。
• 最难采用的选项：基于日期、按账户固定版本（Stripe）。
  • 价值最高：Stripe 表示，自公司于 2011 年创立以来，「始终保持与 API 每个版本的兼容性」。
  • 成本也最高：需要一条由关卡和转换器组成的链路，引擎只计算最新形态，再由各版本转换器降级每个响应；每个历史上的破坏性变更都要有一个模块，并且这些模块需要永久维护。
  • 它在每一轮效率比较中都落败。但有两个条件会让它脱颖而出：一年中多次需要进行破坏性变更，而且集成方数量众多、无法强制迁移。
  • 应根据实际 API 范围和变更频率权衡；切勿因为 Stripe 这么做就盲目采用。
• **删除，而非降级：消费者无法触达，且破坏性变更已按季度或更频繁地发布时，不采用版本控制。**面试回答中的 Q5 和 Q4 合起来，足以排除仅做增量式演进——它承诺永远坚持增量式变更，但当前变更频率已经与此承诺冲突，消费者群体又无法收到预警。应将其从选项中删除，而不是放到最后，因为每次版本机制的成本估算出炉时，「我们只要谨慎一点，坚持做增量式变更就行」都会再次成为计划。重新考虑的触发条件：破坏性变更频率降至大约每年两次以下，或消费者群体变得可枚举、可联系。
• **特意点名 Fielding 的异议，因为同事会提起：**REST 论文的作者认为，版本控制的最佳实践是「不要做版本控制」——可演进的架构不应需要版本号，而在路径中加入版本号会改变一个实际上并未改变的资源 URL。无版本控制这一选项是对该观点的坦诚回应；URI 默认方案则是务实之选。

这个排序是默认方案，不是铁律。应根据面试情况重新排序：

• 有硬性截止日期（Q6）时，优先选择 URI。
• 需要长期维持政策且变更压力较大时（Q4、Q7），优先选择基于日期的版本控制。
• 已有按账户配置基础设施的团队，采用 Stripe 式固定版本的成本会低于此处的估算。

如果 Q1 的回答是 GraphQL，那么这份选项列表根本不适用于阶梯式排序——持续演进是这一范式自身的默认策略；它是对本排序提出理由充分的例外，而非隐藏的第六个选项。如果跨不同 API 表面统一版本控制策略更重要，Shopify 基于日期版本控制的 GraphQL API 则是有据可查的回归方案。

无论最终选择哪种方案：都绝不能将未指定版本的访问作为后备路径。Discord 曾允许这种访问，开发者也直接将其称为反模式——之后移除未指定版本的路径本身就是一次破坏性变更，没人同意过这种变更。

4. 设置通知期限和并行版本数量

根据受众（访谈 Q2/Q5）设置数值，然后对照 references/notice-period-benchmarks.md 中公布的基准进行核验：

• 完全公开的 API：弃用通知期限至少为 12 个月——这是 Google Cloud 和 Shopify 达成共识的最低期限。
• 如果使用方会发布移动应用，或属于大型企业，则将期限提高到至少 24 个月——这是 Microsoft Graph 和 Meta 的最低期限；应用商店的更新周期和企业变更管理都很缓慢，而且不受你控制。
• 合作伙伴/B2B API：将期限写入合同或 SLA，而不是公开政策页面——期限可针对每个合作伙伴协商，写入合同或 SLA 后即可执行。
• 内部 API：用使用方驱动的契约测试和协调部署取代通知期限。 通知期限是对无法直接与使用方协调的一种补偿；内部团队则可以直接协调。
• 并行版本：将活跃版本限制在 2–3 个（这是不同来源的共识）。每增加一个仍在运行的版本，维护、测试和文档成本都会随之增加。Shopify 通过严格的季度自动化流程维持约 4 个版本；Salesforce 数十个版本的情况则是版本不断累积的警示。
• 明确期限从何时开始计算——版本发布时、下一版本发布时，还是宣布弃用时。Meta 的 2 年保证期从 下一 版本发布时开始，这个细节会让实际日期相差数月；若对此含糊不清，之后就会引发支持争议。
• 将公布的日期视为承诺，并将已公布的基准视为最低标准。 Salesforce 曾将一次退役延期两年；Twilio 曾三次延长一次 EOL。延期可以接受，但代价高昂——这会让集成方觉得“最终”日期并非最终日期。引用外部基准时，应写“至少 X 个月”，而不是“恰好 X 个月”。

5. 设计弃用沟通方案

弃用是一个分阶段的过程，而不是一个事件。切勿从宣布直接跳到移除。

• 宣布
• 弃用 - 两个版本都在提供服务，相关信号已启用。
• 日落 - 到达设定日期。
• 移除 - 宽限期结束。

1. 先发布 Deprecation 标头（RFC 9745，标准轨道，2025 年 3 月）。它表示弃用即将到来或已经开始，而且可以在尚未确定日落日期时发布——该 RFC 明确指出，它不会改变任何行为。
2. 日期确定后添加 Sunset 标头（RFC 8594——信息性文档，并非标准轨道；引用时应准确说明）。它会携带该版本停止响应的确切时间戳，且仅出现在已弃用版本的响应中。
3. 添加 Link: rel="successor-version"（RFC 8288），让工具无需从说明文字中抓取信息就能找到替代版本；同时在 OpenAPI 文档中标记 deprecated: true，以便文档和代码生成工具能够显示该信息。
4. 切勿只依赖标头。 大多数 API 不使用这些标头，“原因主要是文化因素”——这意味着大多数集成方的工具也不会显示这些标头。至少还要配合一种能触达用户的渠道：变更日志、开发者控制面板横幅、定向发送给仍在调用已弃用版本的账户的电子邮件（samber/developer-platform-skills@integration-health-monitoring 可找到这些集成及其负责人，并负责发出通知直至截止日期），或响应内警告（Slack 会在 API 响应载荷中嵌入弃用通知——这恰好能触达仍受影响的调用方，成本也低于大规模通知活动）。
5. 负责迁移，而不只是发布公告。 “变更责任规则”：如果你负责弃用某项服务，就要负责迁移其使用方——提供包含具体步骤的迁移指南、可行时提供工具，以及支持渠道。宣布日落后就让集成方自行摸索，是一种明确界定的失败模式，而非折中方案。强制弃用（设定硬性截止日期）意味着必须提供迁移支持；建议性弃用（仅发出警告，由使用方自行安排迁移时间）是默认做法，除非维护成本或安全风险足以证明有必要强制迁移。

弃用沟通与相关的 samber/developer-platform-skills@api-status-communication 有交集——两者的界限是：本技能负责提前数月开展的版本生命周期沟通；后者负责平台当前发生故障时的事故与状态页沟通。

6. 选择日落日期后的强制执行方式

有两种实际做法，如何选择比是否遵循 RFC 更重要：

• **硬性截止（默认建议）：**退役版本返回明确说明的错误——例如 Salesforce 的“端点已停用”消息、Twilio 在其 2008 API 上返回的 404，以及 GitHub 的 410 Gone。集成方会遇到明显的故障，从而诊断并修复问题。
• **平滑回退：**平台将调用已退役版本的请求重新路由至仍可访问的最旧版本（Shopify 已对此作出说明）。仅当无声地保持服务确实比中断更安全时才采用，并明确突出说明——Meta 的 Graph API 就是一个警示案例：“Meta 不会返回错误。它会悄然将你的调用重新路由至较旧但仍可用的版本，因此你的应用会继续运行，只是底层行为已经改变。”有文档说明不等于用户注意到了；Meta 的回退机制写在文档中，却仍不断引发用户对行为悄然变化的投诉。
• 无论采用哪种方式，日落日期后都应设置一个返回 410 Gone 的宽限期，而不是直接断开连接——调用方会收到可用于诊断的错误，而不是一无所获。
• 同一平台的不同接口可以采用不同的强制执行方式：Meta 的 Marketing API 会在约 90 天的窗口后对过期调用返回硬性错误，而核心 Graph API 则会在两年内进行平滑回退——受众的专业程度足以成为区别处理的理由。如果采用不同方式，应将两种方式都写入政策。

7. 建立与影响范围相称的治理机制

治理成熟度，而非方案的复杂程度，才是能够平稳淘汰旧版本的平台与不断产出事故复盘的平台之间的区别。治理分三个阶段——逐步发展，不要一开始就采用最后一个阶段：

1. 基础层：在 CI 中自动执行差异检查／lint，并由指定工程师签字批准。 接入 OpenAPI 差异检查或 lint 工具（Spectral、Zally、oasdiff），以机械方式标记破坏性变更；任何被标记的变更都须由资深工程师批准。这是最低要求，而非成熟的最终形态。将第 2 步中的定义纳入差异检查工具的严重性映射、审批记录和已发布的变更动态，参考 samber/developer-platform-skills@api-changelog-automation。
2. 在 API 范围超出单人审查能力后，设立有书面章程的审查委员会。 Azure 的 Breaking Change Review Board 会阻止未经批准的规范合并；值得借鉴的一点是，其典型产出是「能为当前客户保留现有行为的替代设计」，而不是简单地作出批准／拒绝的裁决。Fuchsia API Council 章程是一份可供调整的公开模板，不必从零起草。
3. 在平台规模下实施完整的指南计划： Google 的 AIP（AIP-180/181 规定了兼容性和稳定性）、强制执行的 lint 工具、可读性认证，以及设计审查。Google 自己的《API Governance at Scale》论文说明了各层机制存在的原因：单靠人工审查「难以扩展」。

每个阶段都适用的规则是：未经治理层批准，不得发布破坏性变更。 AIP-181 将对稳定 API 进行原位破坏性变更称为「极端做法」，并要求治理团队批准——而上述分阶段模式正是为了取代非正式的私下征询流程。

8. 先集思广益提出候选方案，再起草并验证政策

不要在访谈结束后就直接编写成稿。

1. 提出 2-3 个候选政策——每个都应是方案＋时间窗口＋执行机制＋治理机制的完整组合，而非按维度任选搭配；说明各自的取舍，并给出建议方案及理由。例如：采用 Shopify 式日历政策（按季度发布版本、提供 12 个月支持、自动迁移到后续版本）、采用 GitHub 式保守政策（按日期发布版本、提前 24 个月通知、严格返回 410），或在第 3 步的升级条件成立时采用 Stripe 式版本固定策略。
2. 用户选定方案后，参照 references/policy-document-template.md，逐节起草政策文档。每写完一节，都先与用户确认，再写下一节：
   • 方案
   • 定义
   • 时间窗口
   • 沟通
   • 执行
   • 治理
   • 例外
3. 只有在获得对完整文档的明确批准后，才能定稿。

失败模式

以下都是有记录且有名称的事件模式——请根据它们逐一检查草案政策：

• 某个版本同时被弃用且仍是默认版本。 Discord 曾让 v6 同时担任这两个角色约 1.5 年，之后将默认版本直接跳到 v10，跳过了三个版本——你一边把弃用版本继续交给新的集成方，弃用标签就会彻底失去公信力。
• 允许无版本访问——参见步骤 3；之后移除这种访问方式会造成计划外的破坏性变更。
• 因业务动机而跳过流程。 Twitter/X 在 2023 年为付费 API 截止仅提前约 7 天通知——比所有基准都少了两个数量级；当时开发者关系团队已被裁撤，仍照常执行，并导致愿意付费的集成方受到影响。治理纪律恰恰在动机并非技术因素时最重要，因为这时跳过流程最容易让人动心。
• 反复推迟停用日期。 一再延期（Twilio：延期三次）会让集成方不再把你的日期当回事。
• 只通过请求头沟通——这是没有任何工具链会读取的信号，满足了 RFC 的要求，却没有触达任何人。
• 宣布后就不再跟进——这违反了 Churn Rule：没有迁移指南、没有工具、没有定向沟通。
• 未记录的自动回退——实际上这和一份随时可能出现的 Bug 报告没有区别。
• 未定义计时起点——只说“支持 2 年”，却不说明这 2 年从何时开始（Meta 从_下一个_版本发布时起算）。
• 把 GraphQL @deprecated 当作移除。 它只是文档提示；移除需要逐个字段查看使用遥测数据，确认没有真实使用方。

衡量指标

• 从遥测数据统计破坏性变更频率：超过约 2 次/年，说明版本方案或兼容性纪律存在问题（步骤 2 的例外条款）。这是该政策持续跟踪的健康指标。
• 根据使用情况衡量迁移完成度，绝不按日历判断： 当遥测数据显示真实流量为零（或只剩下有意接受的少量流量）时，才可以移除某个版本——公告日期已过，并不能证明谁完成了迁移。
• 弃用版本的流量占比在每轮沟通后持续下降，就能告诉你哪些渠道真正触达了集成方；群发邮件后占比持平，说明该渠道未能奏效，应在停用日期变成事故之前发现这一点。
• 日期兑现情况： 统计停用日期延期次数。已有证据表明延期很常见（Salesforce、Twilio）——但目标仍然是零，因为每次延期都会降低未来所有日期的可信度。流量指标没有行业门槛；应在首次弃用周期中建立基线，并在此基础上持续改进。

调用示例

• “为我们的公共 REST API 编写版本管理和弃用政策——我们从未制定过此类政策，而且已有一项破坏性变更排期。”
• “我们明年要停用 /v1——请设计停用时间表、沟通计划，以及如何处理从未迁移的调用方。”
• “我们的 GraphQL API 应该像 REST API 一样进行版本管理，还是持续演进？请据此起草政策。”

参考资料

• references/versioning-case-studies.md - Stripe 的门控／转换器机制、采取保守策略的平台（Shopify、LinkedIn、AWS、Azure、Google Maps、PayPal/Braintree），以及值得引以为戒的案例（Meta、Discord、Twitter/X）。
• samber/developer-platform-skills@api-error-design - 错误代码也属于 API 契约；弃用错误代码时，会经过该技能定义的弃用流程。
• samber/developer-platform-skills@webhook-platform-design - 事件架构演进遵循此处定义的同一套破坏性变更定义和通知规范。
• samber/developer-platform-skills@public-graphql-api-design - 为第 1 步的持续演进路径提供支持的架构设计（兼容增量扩展的负载、结果联合类型、通过 @deprecated 逐步淘汰字段）；此技能规定了后续移除字段所遵循的通知规范。
• samber/developer-platform-skills@bulk-data-sharing-design - 批量文件／数据湖导出遵循单独的仅增量扩展契约来演进其架构，而非使用此技能的 API 弃用流程。
• samber/developer-platform-skills@sdk-package-publishing - SDK 包版本、预发布渠道和注册表弃用机制均与此处定义的 API 版本解耦。
• samber/developer-platform-skills@public-roadmap-strategy - 在此政策宣布弃用之前，公开路线图不会列出该项；宣布之后，路线图和弃用通知会互相链接。