客户改了一个字段名,你的集成悄无声息地失效
用纯 Python 写 mock 服务器和契约测试,一个下午就能赶在周末营收报表归零前发现变更。
要点速览
- mock 让你在客户 API 就绪前就能写代码、跑测试,但客户改了 API 时它不会告诉你。
- 契约测试共用一份描述文件:你这一侧对照 mock 测试,再把文件里的每个请求发到真实 API 去验证。
- 不要过度 mock:关键流程仍要对真实 API 运行,API 每次变更都要同步更新契约。
设想这样一个场景:周一,你上线了与客户订单系统的集成,所有测试全部通过。周四,客户的后端团队把字段 total 改名为 amount,没有通知任何人。你的代码没有崩溃,只是悄悄返回了 None,周末的营收报表显示为零。
这种事不需要什么复杂的 bug。只要两个团队共用一个集成点,又没有任何东西约束双方遵守当初的约定,就会发生。对前线部署工程师(FDE)来说风险更大,因为 API 通常在客户那一侧。你大概管不了对方的发布节奏,甚至可能看不到对方的代码。
本指南用一个下午完成两件事。第一,mock 客户的 API,让你马上开工。第二,编写契约测试,客户一改 API 你就能知道。
要做出什么?
最终你会得到四个 Python 文件:一份契约文件、一个 mock 服务器、一个针对你这一侧的测试,以及一个对真实 API 运行的验证脚本。你需要 Python 3、一个终端,最好再有一个真实 API 的 staging 地址,用来尝试最后一步。
下面的代码是一个简化的手写版本,只用 Python 标准库,方便看清其中的机制。在真实项目中,这些工作由 Pact 替你完成。
按照 Pact 文档的说法,它是一个“代码优先”的契约测试工具,同时支持 HTTP 和消息两类集成,主要面向写代码的开发者和测试人员。Pact 的具体语法请查阅 docs.pact.io;这里手动重建其机制,让你看清它如何运作。
第 1 步:写代码之前,先把约定写下来
Pact 的工作方式是:consumer 一侧(调用 API 的一方,也就是你)的测试生成一份 pact 文件,描述每一次交互。这里你手写这份文件,以一个假想的客户订单 API 为例:
{
"consumer": "fde-integration",
"provider": "customer-orders-api",
"interactions": [
{
"description": "get an existing order",
"request": {"method": "GET", "path": "/orders/42"},
"response": {"status": 200,
"body": {"id": 42, "status": "PAID", "total": 150000}}
},
{
"description": "order does not exist",
"request": {"method": "GET", "path": "/orders/999"},
"response": {"status": 404, "body": {"error": "not_found"}}
}
]
}
(两条 description 分别表示“获取已有订单”和“订单不存在”。)
把它保存为 contract.json。**检查:**把这份文件交给客户那边的工程师。如果对方确认 API 返回的正是这些内容,你就有了第一份书面约定;双方理解不一致的地方,也会在这一步暴露出来。
404 场景是有意加上的。mock 让你可以测试常规场景之外的情况,而错误场景恰恰是集成代码容易出问题、却很少有人去测的地方。
第 2 步:直接用契约生成 mock
mock API 是一个模仿真实服务的 Web 服务,在真实服务就绪之前,你从第一天起就能用它。这个 mock 直接读取契约,所以两者永远不会脱节:
# mock_server.py:简化版,只按 path 匹配
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
CONTRACT = json.load(open("contract.json"))
class Mock(BaseHTTPRequestHandler):
def do_GET(self):
for it in CONTRACT["interactions"]:
if it["request"]["path"] == self.path:
res = it["response"]
self.send_response(res["status"])
self.send_header("Content-Type", "application/json")
self.end_headers()
self.wfile.write(json.dumps(res["body"]).encode())
return
self.send_response(500)
self.end_headers()
HTTPServer(("localhost", 8001), Mock).serve_forever()
python3 mock_server.py &
curl -i http://localhost:8001/orders/999
**检查:**你应当看到 HTTP/1.0 404 和响应体 {"error": "not_found"}。调用契约中没有的 path 会返回 500。这个错误是故意的:说明你的代码在调用约定之外的东西。
第 3 步:用 mock 测试你的代码
下面是真正的集成代码和它的测试:
# client.py
import json, urllib.request, urllib.error
def get_order_total(base_url, order_id):
try:
with urllib.request.urlopen(f"{base_url}/orders/{order_id}") as r:
return json.load(r).get("total")
except urllib.error.HTTPError as e:
if e.code == 404:
return None
raise
# test_consumer.py
from client import get_order_total
BASE = "http://localhost:8001"
assert get_order_total(BASE, 42) == 150000
assert get_order_total(BASE, 999) is None
print("consumer OK")
检查:python3 test_consumer.py 输出 consumer OK。注意 .get("total") 这一行:字段消失时,函数不会报错,而是返回 None。这正是开头那种静默失败,大量集成代码都是这样写的。
mock 是一个隔离的 API,不受服务、数据库或外部系统变更的影响。因此即使客户的 staging 环境宕机,这个测试也照样能跑。
但这种隔离同时也是弱点。如果客户把 total 改名为 amount,mock 仍然返回 total,测试照样通过。客户还没就绪时,mock 帮得上忙;客户改了 API,它却不会告诉你。
第 4 步:拿契约去验证真实 API
这是另一半,也是契约存在的意义。Pact 把这一步称为 provider 验证:把 pact 中的每个请求发给 provider。契约测试通过分别单独测试每个应用来检查集成点。你这一侧对照 mock 测试;客户那一侧用同一份文件测试。
# verify_provider.py:简化版,只比较状态码和字段名,不比较值
import json, sys, urllib.request, urllib.error
contract = json.load(open("contract.json"))
base = sys.argv[1]
fails = 0
for it in contract["interactions"]:
req, exp = it["request"], it["response"]
try:
r = urllib.request.urlopen(base + req["path"])
status, body = r.status, json.load(r)
except urllib.error.HTTPError as e:
status, body = e.code, json.load(e)
missing = [k for k in exp["body"] if k not in body]
if status != exp["status"] or missing:
fails += 1
print(f"FAIL {it['description']}: status={status}, 缺少 {missing}")
sys.exit(1 if fails else 0)
python3 verify_provider.py https://staging.customer.example
脚本有意只比较字段名、不比较值,因为客户 staging 环境里的 42 号订单,总额肯定不会恰好是 150000。**检查:**客户重命名字段时,你会看到 FAIL get an existing order: status=200, 缺少 ['total'],退出码为 1。
契约测试能大大加快排查速度,原因就在这条输出里:错误信息直接指出是哪个字段、哪次交互,而不是仪表盘上一个莫名其妙的零。
注意其中一个隐含假设:staging 上必须存在 42 号订单。要和客户约定固定的测试数据,否则验证步骤会因为与契约无关的原因失败。
第 5 步:放进 CI,不必靠人记着去跑
一个需要有人记着去跑的脚本,迟早会被忘掉。在 CI 中定时运行 verify_provider.py。由于脚本失败时返回非零退出码,流水线会自动变红。
使用 Pact 时,Pact Broker 负责与 CI 的对接。当需要验证的 API 和团队越来越多,就是放弃手写版本、改用这个工具的时候了。
三个常见错误
第一是过度 mock。原则是避免过度 mock,尽可能使用真实 API,尤其是关键流程。如果客户的支付流程只在 mock 上跑过,那就等于没真正测试过。
第二是契约一成不变。测试只有随 API 变更同步更新,才能准确反映系统。客户宣布 API 变更时,第一个要改的是 contract.json,而不是代码。mock 和验证步骤会自动跟上。
第三是匹配过严。如果对照真实数据断言每一个值,测试会天天失败,团队很快就学会无视它。
这项技能在客户现场怎么用?
驻场客户的第一周,API 往往还没做完,文档也已过时。写好 contract.json 交给客户的工程师,是在写下第一行代码之前暴露双方理解分歧的最快方式。
集成上线到生产环境后,每晚跑一次验证,能让你第一时间知道客户刚改了 API,而不必等对方打电话来。
简历上不要只写“熟悉 Pact”。要写明你为多少个交互建立了契约,以及在上线前拦下了哪些类型的变更。
你的集成代码只有在客户 API 保持双方约定的样子时才能正确运行。契约测试就是每天检查这一点的手段。
这篇文章对你有帮助吗?
感谢你的反馈!