# 客户改了一个字段名，你的集成悄无声息地失效

> 用纯 Python 写 mock 服务器和契约测试，一个下午就能赶在周末营收报表归零前发现变更。

原文: https://fdetimes.net/zh/guides/mock-client-api-contract-testing/

设想这样一个场景：周一，你上线了与客户订单系统的集成，所有测试全部通过。周四，客户的后端团队把字段 `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 为例：

```json
{
  "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 直接读取契约，所以两者永远不会脱节：

```python
# 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()
```

```bash
python3 mock_server.py &
curl -i http://localhost:8001/orders/999
```

**检查：**你应当看到 `HTTP/1.0 404` 和响应体 `{"error": "not_found"}`。调用契约中没有的 path 会返回 500。这个错误是故意的：说明你的代码在调用约定之外的东西。

## 第 3 步：用 mock 测试你的代码

下面是真正的集成代码和它的测试：

```python
# 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
```

```python
# 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，它却不会告诉你。

**要点:** mock 让你在客户未就绪时也能干活；契约则在客户改动时告诉你。

## 第 4 步：拿契约去验证真实 API

这是另一半，也是契约存在的意义。Pact 把这一步称为 provider 验证：把 pact 中的每个请求发给 provider。契约测试通过分别单独测试每个应用来检查集成点。你这一侧对照 mock 测试；客户那一侧用同一份文件测试。

```python
# 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)
```

```bash
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 保持双方约定的样子时才能正确运行。契约测试就是每天检查这一点的手段。

**本周动手试试:**

- 选一个你的项目调用的外部 API，为 2 个交互写一份 contract.json：一个成功场景，一个错误场景。
- 对该 API 的 staging 环境运行 verify_provider.py，并把它加入 CI 每天运行。
- 在简历上加一条具体内容：你为多少个交互建立了契约测试，在上线前拦下了哪些类型的错误。

## 信源

- [What is API mocking?](https://blog.postman.com/what-is-api-mocking/)

- [What is API Mocking? Definition, Guide, and Best Practices](https://katalon.com/resources-center/blog/what-is-api-mocking)

- [Introduction | Pact Docs](https://docs.pact.io/)

- [How Pact works | Pact Docs](https://docs.pact.io/getting_started/how_pact_works)

- [A Complete Guide to API Contract Testing](https://testsigma.com/blog/api-contract-testing/)

- [How to run API integration tests](https://www.merge.dev/blog/api-integration-testing)
