复盘：缺失契约测试如何让破坏性变更进入生产环境

Provider 团队在一次清理 PR 中重命名了一个 JSON 字段。OpenAPI 规格已同步更新。Provider 端所有测试均通过。两个服务之间不存在契约测试。Consumer 端开始静默地收到一个必填字段的 null 值，直到四个小时后仓库操作员发现拣货单上的商品编码一片空白，此时已有 340 笔订单带着缺失的 SKU 数据被创建。以下是这次事故的复盘还原。

发布于 2025-12-09 · ✓ 已更新 2026-05-06 · 约 13 分钟 · 作者：Daniel Marsh · 审稿政策：编辑政策

事件经过

Catalog 服务团队正在进行一次例行清理冲刺。其中一个 PR 将 GET /v2/catalog/products/{id} 端点的 JSON 响应字段从 product_sku 重命名为 item_sku。这次重命名是为了让字段名与团队内部的领域模型保持一致——六个月前，限界上下文中的 "product" 已经被 "item" 取代。OpenAPI 规格在同一个 PR 中同步更新。变更看起来很干净：一个字段重命名、规格已更新、Catalog 服务的所有测试全部通过。

Order 服务消费了这个端点。它从 Catalog 的响应中解析 product_sku 字段来填充每笔订单的 SKU 列。Catalog 部署之后，Order 服务开始收到不再包含 product_sku 的响应。Order 服务的反序列化逻辑没有因为字段缺失而报错——它静默地将 SKU 列赋值为 null，然后继续处理订单。

以下是重命名前后 Catalog 响应的对比：

{
  "id": "cat-9821",
  "product_sku": "WH-4420-BLU",
  "name": "Widget Housing — Blue",
  "price_cents": 1499,
  "currency": "USD"
}

{
  "id": "cat-9821",
  "item_sku": "WH-4420-BLU",
  "name": "Widget Housing — Blue",
  "price_cents": 1499,
  "currency": "USD"
}

Order 服务仍然在解析 product_sku。字段已不存在，值解析为 null。订单继续流转，只是 SKU 数据变成了空白。没有错误被抛出，没有告警被触发，没有测试失败。四个小时后，一位仓库操作员报告拣货单上的商品编码为空，无法在货架上定位商品——问题才被发现。

团队本可以在流水线的三个更早环节检测到这次破坏性变更。第一，在 CI 中运行规格差异比对工具，就能在 PR 合并前标记被移除的字段——这只需几秒钟即可配置，且能捕获最常见的意外破坏。第二，consumer 驱动的契约测试会在 Catalog CI 流水线中失败，因为 Order 服务声明的预期将不再匹配 provider 的输出。第三，对下游字段 null 率进行金丝雀分析，就能在首个生产请求发出后的几分钟内发现问题。但这些机制一个都不存在。团队经历了四个小时的静默数据损坏，因为每一道检测防线都是他们计划"以后再加"的东西。

时间线

周一

T-0    10:14 AM   PR #3847 合并——将 Catalog 服务中的
                  product_sku 重命名为 item_sku。OpenAPI 规格
                  在同一次提交中更新。Provider 端所有 CI 检查通过。

T+15m  10:29 AM   Catalog 服务通过自动化流水线部署到生产环境。
                  部署门禁未检查 consumer 兼容性。

T+45m  10:59 AM   Order 服务开始在所有新订单中收到 product_sku
                  为 null。未记录任何错误——该字段在 Order 服务
                  的反序列化模型中被映射为可选字段。

T+2h   12:14 PM   340 笔订单以 null SKU 数据创建。订单处理
                  继续正常运行。没有告警规则监控 SKU 列的
                  null 率。

T+4h   02:14 PM   仓库操作员向运营 Slack 频道报告拣货单为空白。
                  拣货单显示的订单行项目没有商品编码。仓库团队
                  无法在不逐一手动查询的情况下完成拣货。

T+4h   02:26 PM   值班工程师开始排查。追踪空白 SKU 至订单表中的
  12m             null 值。检查 Catalog 服务响应后发现
                  product_sku 字段已消失，被 item_sku 取代。
                  确认 PR #3847 为原因。

T+4h   02:44 PM   Catalog 服务回滚到上一版本。product_sku 字段
  30m             在生产响应中恢复。

T+5h   03:14 PM   执行数据回填脚本。查询 Catalog 服务获取 340 条
                  受影响订单行项目的正确 SKU 值，修补订单表。

根因分析

直接原因是一次破坏性字段重命名在未通知 consumer 的情况下被部署。但根本原因是结构性的：没有任何机制能检测到字段重命名会破坏 consumer，也没有任何流程要求检查。

四个具体的缺口共同导致了这次事故：

1. OpenAPI 规格存在，但没有任何东西将其与 consumer 关联执行。Catalog 团队维护着一份 OpenAPI 规格，并在同一个 PR 中将其与字段重命名一起更新。规格是准确的。但准确不等于执行。没有工具将新版规格与旧版进行比对来标记破坏性变更。像 oasdiff 这样的工具本可以检测到被移除的字段并阻止合并。

2. 不存在 consumer 驱动的契约测试。Order 服务没有 Pact 契约或等效测试来声明："Order 服务期望 Catalog 响应中包含名为 product_sku 的字段。"Consumer 驱动的契约测试会在 Catalog 服务的 CI 流水线中运行，并在字段被重命名时失败——在 PR 合并之前。

3. PR 评审发现了规格更新，但没有发现对 consumer 的影响。两位工程师评审了 PR #3847。两人都确认规格与代码变更一致。但没有人问："谁在消费这个字段？"当时使用的规格评审检查清单不包含针对字段级变更的 consumer 影响评估。评审验证了内部一致性（代码与规格匹配），但没有验证外部兼容性（规格变更对 consumer 是否安全）。

4. Provider 端测试通过，因为它们测试的是新字段名。Catalog 服务的集成测试在同一个 PR 中被更新，断言 item_sku 而非 product_sku。从 provider 的角度看，每个测试都是正确的。这些测试验证的是 provider 生产了什么，而不是 consumer 期望收到什么。这正是仅依赖 provider 端测试的根本局限：它无法检测 consumer 的破坏，因为它根本不知道 consumer 依赖了什么。

影响

直接影响限于单一业务功能（订单履行），但下游效应波及多个团队，每一步都需要人工介入。

在订单交付层面没有产生面向客户的影响——回填在所有 340 笔订单发货前完成了修正。但已经到达仓库的 87 笔订单需要拣货团队手动干预，导致该班次剩余时间的履行吞吐量下降。

这次事故的完整成本远不止表格中的 9 人时。Catalog 团队的部署流水线被冻结了 24 小时以等待评审流程更新，这阻塞了另外两个已准备就绪的 PR。复盘会议本身耗时 3.5 小时，涉及 6 名工程师和 1 名工程经理——大约 25 人时的会议时间。Order 团队又额外花了一天编写回填脚本并验证修正后的数据。再算上信任成本：仓库运营团队提交了一份内部可靠性投诉，在此后三个月里 Catalog 团队每次部署前都必须先通知运营频道。一次字段重命名——契约测试流水线本可以在 CI 中零成本捕获——却产生了超过 40 人时的计划外工作和数周的流程摩擦。

五项改进措施

复盘会议产出了五项具体改进措施，每项都有可交付物、负责人和截止时间。按影响范围排序：前两项防止此类事故再次发生；后三项解决使其成为可能的系统性缺口。

措施 1：使用 oasdiff 检测破坏性变更

杠杆最高的修复是自动化的。oasdiff 比对两个版本的 OpenAPI 规格并报告破坏性变更：被移除的字段、被重命名的字段、类型变更、枚举值缩减。将其作为 Catalog 服务流水线中的 CI 步骤意味着，PR #3847 会以明确的消息使 CI 失败：

oasdiff breaking --base main --revision HEAD

BREAKING CHANGES DETECTED:
  GET /v2/catalog/products/{id}
    Response 200:
      - Field 'product_sku' was removed (breaking)
      - Field 'item_sku' was added (non-breaking)

1 breaking change(s) found. Pipeline blocked.

这一检查在数秒内完成，不需要任何 consumer 端配置，且能捕获最常见的意外破坏性变更类型：字段移除或重命名。

契约测试能够从根本上防止这一整类故障，因为它将 consumer 的实际依赖编码为可执行的断言。没有契约测试时，判断一次变更是否会破坏 consumer 的唯一方式就是部署上去然后等着出问题。有了契约测试，"这次变更会不会影响到谁？"这个问题在 CI 阶段就能得到解答——在变更到达任何一台生产服务器之前。投入很小——花几个小时搭建 Pact 或类似框架即可——而回报是不对称的：你避免的是动辄耗费数天工程时间、造成仓库中断和跨团队信任损耗的事故。本站的复盘有效性指南介绍了如何追踪这些预防性投入是否真正发挥了作用。

措施 2：使用 Pact 实现 consumer 驱动的契约测试

oasdiff 捕获的是规格层面的变更，但无法验证 consumer 是否正确解析了特定字段。Pact 契约测试弥补了这一缺口。Order 服务发布一份契约声明："当 Order 服务调用 GET /v2/catalog/products/{id} 时，响应中必须包含一个名为 product_sku、类型为 string 的字段。"这份契约在 Catalog 服务的 CI 流水线中被验证。如果 Catalog 服务重命名了该字段，Pact 验证会在合并前失败。

oasdiff（规格层面）与 Pact（运行时层面）的结合形成了两道独立的防线。其中任何一道单独存在就能阻止这次事故。两者协同则能捕获单一层面可能遗漏的破坏性变更——例如，响应符合规格但由于逻辑变更返回了非预期值的情况。

措施 3：Consumer 影响评审门禁

工具捕获的是已知模式。规格评审门禁捕获的是工具尚未覆盖的模式。更新后的 PR 模板现在要求任何修改 API 响应 schema 的 PR 都包含一个 "Consumer 影响" 部分：

## Consumer 影响

修改的字段：product_sku → item_sku（重命名）
已知 consumer：Order 服务、Analytics 流水线、Partner API
已通知 consumer 团队：[ ] Order 团队  [ ] Data 团队  [ ] Partner 团队
破坏性变更：是 / 否
迁移计划：[废弃时间线链接 或 N/A]

在 "已通知 consumer 团队" 的复选框被勾选之前，PR 无法合并。这是一个流程门禁而非技术门禁，它要求 PR 作者回答一个 PR #3847 从未提出的问题：谁在读这个字段？

措施 4：必填字段的 null 率告警

即使有了检测和评审门禁，纵深防御仍然需要运行时监控。Order 服务现在有一个 Datadog monitor，当 sku 列在任意 15 分钟窗口内的 null 率超过 1% 时触发告警。正常运行时，null 率为 0%——每笔订单都有 SKU。飙升至 100%（如本次事故中的情况）会在第一笔受影响订单产生后 15 分钟内触发 PagerDuty 告警，将检测窗口从 4 小时缩短到 20 分钟以内。

这个告警无法阻止事故发生，但能将影响范围从 340 笔订单缩减至约 30 笔。

措施 5：在 API 治理中制定字段重命名策略

最后一项措施解决的是组织层面的缺口。API 治理指南现在包含字段重命名策略：

• 字段重命名被视为破坏性变更，无论旧字段名是否"不正确"。
• 迁移路径为：在旧字段旁边添加新字段、通知 consumer、设定废弃截止时间（最短 2 个 sprint），仅在所有 consumer 完成迁移后才移除旧字段。
• 直接重命名（在同一个 PR 中移除旧字段、添加新字段）对于任何出现在版本化 API 响应中的字段都是被禁止的。

在这一策略下，PR #3847 会在 product_sku 旁边添加 item_sku，并在 OpenAPI 规格的 description 字段中注明废弃说明。Order 服务团队可以按自己的节奏完成迁移，旧字段只有在 Order 服务确认不再使用后才会被移除。

规格本应捕获的问题

在整个事故过程中，Catalog 服务的 OpenAPI 规格始终是准确的。重命名之前，它记录了 product_sku。重命名之后，它记录了 item_sku。规格从未出错。只是从未有人将它与依赖它的消费者进行比对。

这就是规格与契约之间的差距。规格描述的是服务生产了什么。契约描述的是服务生产了什么以及其消费者期望收到什么。规格被更新了。契约不存在。这两个事实之间的距离恰好是 340 笔带有缺失 SKU 数据的订单。

如果规格评审包含一项 consumer 影响检查——哪怕只是一个问题，"谁在读这个字段？"——这次重命名就会在 PR 批准之前被标记。Catalog 团队会发现 Order 服务、Analytics 流水线和 Partner API 都在消费 product_sku。这次重命名就会变成一次迁移，而不是一次清理。

修复不仅仅是工具。oasdiff 和 Pact 等工具将检测自动化了，但它们作用于已经被编码的模式。更深层的修复是将 "consumer 影响" 作为任何字段级变更的规格模板的必填部分。这会在工具运行之前、在采取行动的成本最低的节点强制提出这个问题。

在实施全部五项改进措施后，Catalog 团队进行了一次受控实验：他们在测试分支中故意引入了一次破坏性字段重命名，并验证该变更在三个独立环节被拦截——oasdiff 标记了规格差异，Pact 契约验证失败，PR 模板强制作者列出受影响的 consumer。这些防线中的任何一层都足以阻止最初那次事故。这种冗余是有意为之。工具有盲区（oasdiff 无法捕获保留字段名但改变语义的变更），流程门禁依赖人的自觉（有人可能跳过检查清单），而契约测试需要 consumer 已编写好自己的契约。纵深防御与spec-first 错误处理背后的原则相同：你不依赖单一机制，因为单一机制会失效。

本站的计费事故复盘从不同角度得出了类似结论：规格存在，规格准确，但规格仍然未能阻止事故——因为它没有回答真正重要的问题。在那个案例中，缺失的问题是 "这个端点是否可以安全重试？"在本案例中，缺失的问题是 "谁依赖这个字段？"这两个问题在规格评审时只需几分钟就能提出，而在生产出问题后则需要数小时才能回答。

API 响应中的每个字段都是对某个消费者的承诺。规格记录承诺。契约测试验证承诺。评审门禁确保有人问一句：这个承诺是否即将被打破。三层防线缺一不可，因为每一层都能捕获另外两层遗漏的失败。导致这次事故的字段重命名，只要其中任何一层存在，就会被拦截。