字段名没动、类型悄悄变了，下游一夜全崩：用 Pact 消费者驱动契约测试把『我以为』钉成会失败的构建

一次上线后，运营后台的订单金额全变成了 NaN。翻日志才发现，上游订单接口把 amount 从 number 悄悄改成了 string——字段名一个没动，返回码还是 200，接口文档没更新。下游三个消费者各有各的崩法：结算服务在做金额相加时抛了类型错，报表服务把 "99" 当字符串拼进了合计，推送服务因为一个原本必返的 status 字段这次偶发缺省，直接 KeyError。

联调复盘时，三方的说法惊人一致：「我以为你没改。」微服务之间最贵的 bug，往往不是某个函数的逻辑写错了，而是接口契约悄悄漂移，却没有任何一条测试在替它站岗。 返回码 200 只说明请求没炸，它从不保证「返回的结构还是下游当初依赖的那个结构」。

这篇讲的就是怎么给「上下游之间的接口约定」写一份会失败的断言——用 Pact 的消费者驱动契约测试，把每个人心里那句「我以为」，钉成一条上游改坏就红的构建。

一、契约漂移是什么：返回码 200，结构却变了

先给结论：契约(contract)不是一个接口文档，是「上游承诺返回什么结构、下游依赖其中哪些字段」这份双向约定。文档会过期，约定不会自动校验——这就是漂移能溜过去的根本原因。

漂移最阴险的地方在于它对现有测试完全隐形。你的单元测试测的是自己服务内部的逻辑，绿；你的接口自动化只断言了 status_code == 200 和几个关键字段存在，也绿；端到端联调那天上游还没改，照样绿。等到上游把 amount 的类型从 number 换成 string、把某个必返字段改成偶发缺省，所有绿灯都没变，坏数据已经流到了下游的解析层。

契约漂移 = 返回码没变、语义变了。 它绕过了「请求成没成功」这一层检测，直接命中「下游能不能正确消费」这一层——而这一层，恰恰是传统测试最薄的地方。

更麻烦的是，契约漂移的破坏是分散爆发的。同一次上游改动，会让每个下游崩在各自不同的解析点上：强类型的服务抛异常、弱类型的服务默默拼错数据、依赖必返字段的服务偶发 KeyError。没有一个统一的报错能告诉你「根因是上游改了结构」，你只能一个个下游去查，最后才拼出「原来是同一处漂移」。这也是为什么它比逻辑 bug 更贵——逻辑错通常崩在一处、指向明确，契约漂移却能让三个团队各自加班、各自甩锅，直到有人把三条崩溃链路并排一看，才发现源头是同一行改动。

二、把契约测试锚回旧知识：给「我以为」补一条会失败的断言

这件事你其实早就干过，只是对象不同。

想想你写接口测试时用的 Mock。你 Mock 一个下游依赖，塞进去一个「你以为它会返回的样子」，然后测自己的逻辑。问题是：这个 Mock 里的返回结构，是你单方面脑补的。上游真改成什么样，Mock 不知道，也不会告诉你——它永远返回你当初手抄的那一份，于是你的测试永远绿，绿得毫无意义。

消费者驱动契约测试，就是把这个「单方面脑补的 Mock」升级成一份双方都认、能自动校验的契约。流程反过来走：不再由下游猜上游返回什么，而是由下游显式声明「我作为消费者，期望上游返回长这样」，这份声明被落成一个 pact 契约文件、存到中心（Pact Broker），上游每次构建时拉下来跑一遍 provider verification——一旦上游真实返回偏离了任何一个下游的期望，上游的构建立刻红。

锚回旧知识就是一句：契约测试是给「上下游的接口约定」写断言，等价于把 Mock 的「我以为的返回」，变成一份会在 CI 里自动比对、偏离即失败的活契约。断言的对象从「我自己服务的返回值」，扩展到了「我和上游之间的那份约定」。

三、Pact 两段式代码：消费者声明期望 + 提供者验证契约

Pact 的用法分两段。第一段在消费者侧：声明「我期望上游返回什么」，生成 pact 契约文件。

# test_order_consumer_contract.py —— 消费者侧：声明期望，生成 pact 契约文件
# 代码为 pact-python 概念示例，具体 API 可能随版本略有出入
from pact import Consumer, Provider, Like, Term

# 我是订单前台(OrderWeb)，我依赖订单服务(OrderService)
pact = Consumer("OrderWeb").has_pact_with(Provider("OrderService"), port=1234)

(pact
 .given("订单 A1001 已支付")                       # 前置状态
 .upon_receiving("查询订单 A1001 的请求")           # 交互场景名
 .with_request("get", "/orders/A1001")             # 我作为消费者会这样请求
 .will_respond_with(200, body={
     "order_id": Like("A1001"),                    # Like：值可变，但类型/结构必须一致
     "amount":   Like(99),                         # 关键：声明 amount 必须是 number
     "status":   Term(r"^(paid|refunded)$", "paid"),  # Term：值必须匹配这个正则
 }))

# 把这个交互落成 pact 契约文件，之后推到 Pact Broker 供上游验证
with pact:
    result = pact.verify()   # 生成本地契约；CI 里再 publish 到 Broker

第二段在提供者侧：上游拉下所有下游的契约，跑 provider verification，真实返回一偏离契约就红。

# provider_verification.py —— 提供者侧：跑真实服务，比对是否满足所有下游契约
# 上游每次构建都跑这一段，一旦真实返回偏离任何一个下游期望，构建直接失败
from pact import Verifier

verifier = Verifier(provider="OrderService", provider_base_url="http://localhost:8000")

success, _ = verifier.verify_provider(
    broker_url="https://pact-broker.internal",     # 从 Pact Broker 拉下游契约
    publish_version="1.4.0",                        # 发布本次验证结果，供下游查「能不能安全上线」
    provider_states_setup_url="http://localhost:8000/_pact/setup",
)
assert success, "上游真实返回偏离了下游契约 —— 构建拦下"

为什么这么写、踩过什么坑。 第一，amount 我用了 Like(99) 而不是写死 99——Like 的语义是「值可以变，但类型和结构必须一致」，这正好卡住了开头那个 Bad Case：上游把 number 改成 string，Like(99) 会立刻判违约。第二，status 用 Term(正则) 是因为它的取值是一个有限枚举，我要守的是「只能是 paid 或 refunded」这条契约，而不是某个具体值。第三，最大的坑是把契约写成端到端的功能测试——契约只验「结构和类型对不对」，不验「业务逻辑算得对不对」，前者快、稳、能进 CI，后者交给端到端。第四，provider verification 必须挂进上游的构建流水线才有意义：契约文件存在 Broker 里只是「记录了约定」，只有上游每次改动都自动比对一遍，漂移才会当场被撞红，而不是等下游上线后崩了才回头查。

四、手工联调 vs 消费者驱动契约测试：五个维度看清差别

把两种做法放到五个维度上对照，为什么契约测试值得进 CI 就很清楚了：

再补一张三者定位对照表，避免把契约测试和 Mock、端到端混为一谈——它们各守一层，不是替代关系：

五、把契约测试接进 CI：让它成为一条会拦合并的门禁

契约测试的价值，只有在它「自动跑、偏离就拦」时才成立。落地节奏通常是三步：消费者侧把 pact 契约文件在每次提交时生成并 publish 到 Pact Broker；提供者侧把 provider verification 挂进构建流水线，改一次接口就比对一遍所有下游契约；再用 Broker 的「can-i-deploy」能力，在上线前问一句「我这个版本，和当前所有下游的契约还兼容吗」，不兼容就拦住发布。

这样一来，开头那个 Bad Case 的命运就变了：上游把 amount 从 number 改成 string 的那一刻，provider verification 直接红，PR 合不进去；就算侥幸合了，can-i-deploy 也会在上线前拦下。契约漂移从「上线后下游静默崩」，变成了「改动时上游当场红」。 这就是把 Mock 里那句私下的「我以为」，升级成一份双方都认、会失败的公开约定后，整条链路拿到的确定性。

写在最后

字段名没动、类型悄悄变了、返回码还是 200——这类 bug 之所以贵，不是因为它难修，而是因为它发现得太晚：晚到下游已经崩在生产、晚到三方还在互相说「我以为你没改」。

对测试工程师来说，这压根不是新概念。你早就懂「Mock 里的返回是脑补的、不能全信」，也早就懂「断言要写进 CI 才有意义」。契约测试只是把这两件事合到了一起：让下游把「我以为」显式写成契约，让上游每次改动都自动比对一遍。

返回码 200 只证明请求没炸，从不证明结构没漂——契约测试，就是给「结构没漂」这件事补一条会失败的断言。