# 在客户端拦住客户的坏 JSON，再离线测试

> 只替换传输层，同一个客户端既能调用真实 API，也能离线跑测试，代码一行不改。

原文: https://fdetimes.net/zh/guides/typed-python-client-offline-tests/

进驻客户现场的第一周，接触最多的往往是对方的内部 API：文档不全，响应慢，还时不时返回与描述不符的 JSON。如果代码里到处都是 `resp.json()["total"]`，只要缺一个字段，演示就会崩。而堆栈信息指向的，是埋在三层之下的某一行。

本指南教你用 httpx 和 Pydantic 写一个小巧的类型化 Python 客户端，再配一套不需要网络的测试，避开这个坑。示例使用一个假想的订单 API，它有一个 `/orders/{id}` 端点。订单 API 是虚构的，但文中用到的每个函数和类都出自 httpx、Pydantic 和 pytest 的官方文档。

你需要 Python 3、一个 virtualenv，再花几分钟做准备：

```bash
pip install httpx pydantic pytest
```

## 第 1 步：把数据契约写成模型

调用网络之前，先写下你*认为* API 会返回什么。这个模型就是你的代码与客户系统之间的契约。

```python
# orders_client/models.py
from pydantic import BaseModel

class Order(BaseModel):
    id: int
    status: str
    total: float
```

根据 Pydantic 文档，只要数据与模型不符，库就会抛出 `ValidationError`。反过来，校验一旦通过，Pydantic 保证对象的字段符合声明的类型。本指南中的客户端正是依赖这一保证，下游代码不必再担心 `total` 是否存在。

**检查：** 在 REPL 中调用 `Order.model_validate_json('{"id": 1, "status": "new"}')`。你应该看到一个 `ValidationError`，其中只有一条错误，类型为 `missing`，消息为 `Field required`，`loc` 的第一个元素是 `total`。

## 第 2 步：为什么只要一个 httpx.Client？

很多人在每个函数里直接调用 `httpx.get()`。这样能跑，但 httpx 文档说得很清楚：除了实验、一次性脚本或原型，都应使用 `Client` 实例。因此，面向客户 API 的客户端应当只持有一个 `httpx.Client`，并在所有请求中复用。

```python
# orders_client/client.py
import httpx
from .models import Order

class CustomerApiError(Exception):
    def __init__(self, status_code: int, body: str):
        super().__init__(f"客户 API 返回 {status_code}：{body[:200]}")
        self.status_code = status_code
        self.body = body

class OrdersClient:
    def __init__(self, base_url: str, transport=None, timeout: float = 10.0):
        self._http = httpx.Client(
            base_url=base_url, timeout=timeout, transport=transport
        )

    def get_order(self, order_id: int) -> Order:
        resp = self._http.get(f"/orders/{order_id}")
        try:
            resp.raise_for_status()
        except httpx.HTTPStatusError as exc:
            raise CustomerApiError(exc.response.status_code, exc.response.text) from exc
        return Order.model_validate_json(resp.content)

    def close(self) -> None:
        self._http.close()
```

这段代码里有三个决定值得注意。第一个是 `base_url`：httpx 会把这个 URL 加在每个请求前面，所以每个方法只需传路径。从 staging 切换到生产环境，只要改一个字符串。

第二个是超时。默认情况下，网络超过 5 秒没有动静，httpx 就会抛出 `TimeoutException`。对耗时较长的报表来说，这可能太短；对本应立即响应的端点来说，又可能太长。

这里把超时显式写出来，读代码的人就能明白这是刻意的选择，而不是忘了改的默认值。10 秒仅作示例，实际取值请向客户询问该端点的 SLA。

最后一个是 `raise_for_status()`。它把所有 2xx 范围之外的响应转换成 `HTTPStatusError`，其中同时带有请求和响应。客户端再把它转换为 `CustomerApiError`，这样遇到 HTTP 错误时，上层捕获的是项目自己的错误，不必了解 httpx 的错误类。

这个精简版的局限也要说清楚：`ValidationError` 和 `httpx.TimeoutException` 仍会直接抛给调用方。不处理 `ValidationError` 是有意为之，好让第 4 步的测试清楚地暴露坏 payload。在真实项目中，可以把这两个也包装成自己的错误；只有这样，上层才真正只需捕获项目错误。

**检查：** `get_order` 返回的是 `Order`，而不是 `dict`。编辑器现在可以自动补全 `.total` 了。

## 第 3 步：transport 参数有什么用？

注意构造函数中的 `transport=None` 参数，测试能离线运行就靠它。根据 httpx 文档，`MockTransport` 接收一个 handler 函数，把每个请求映射到预先定义的响应，不会有任何真实请求离开本机。

接入也很简单，因为 `httpx.Client` 本身就接受 `transport` 参数：传入 `httpx.MockTransport(handler)` 即可。被测代码保持不变，只替换了底下的传输层。

James Bennett 在文章《Don't mock Python's HTTPX》中推荐的正是这种做法：使用 HTTPX 内置的 mock transport，而不是 mock HTTPX 本身或其内部实现，以减少对 mock 对象的依赖，省去很多麻烦。

```python
# tests/test_client.py
import httpx
import pytest
from pydantic import ValidationError
from orders_client.client import OrdersClient, CustomerApiError

def handler(request: httpx.Request) -> httpx.Response:
    if request.url.path == "/orders/42":
        return httpx.Response(200, json={"id": 42, "status": "shipped", "total": 19.5})
    if request.url.path == "/orders/7":
        return httpx.Response(200, json={"id": 7, "status": "shipped"})
    return httpx.Response(404, json={"error": "not found"})

@pytest.fixture
def client():
    c = OrdersClient("https://api.customer.example", transport=httpx.MockTransport(handler))
    yield c
    c.close()
```

在 pytest 中，测试函数只要把 fixture 声明为参数就能拿到它。因此每个测试都共用一个跑在 mock 上的客户端，无需重复准备。

## 第 4 步：三种结果都要测，不只测正常路径

调用客户系统的客户端至少有三种结果：数据正确、数据结构不对、HTTP 错误。每种都需要单独的测试。

```python
def test_order_ok(client):
    order = client.get_order(42)
    assert order.total == 19.5

def test_payload_missing_field(client):
    with pytest.raises(ValidationError):
        client.get_order(7)

def test_404_becomes_custom_error(client):
    with pytest.raises(CustomerApiError) as exc:
        client.get_order(999)
    assert exc.value.status_code == 404
```

仔细看订单 7。API 返回状态码 200，看起来是成功，但缺了 `total`。没有模型的话，要等到某个营收函数遇到 `KeyError`，错误才会暴露。

有了模型，`get_order(7)` 会立刻因 `ValidationError` 停下，错误条目指明 `total` 字段，消息为 `Field required`。哪个字段坏了、出在哪个端点，一目了然。

**检查：** 关掉 Wi-Fi，运行 `pytest -q`。三个测试应该仍然全部通过。

**要点:** 客户的坏数据应当拦在客户端门口，绝不能放进业务逻辑。

## 什么时候该改用 pytest-httpx？

手写的 handler 容易看懂，但有个盲点：如果为代码从未调用的路径准备了响应，测试照样通过。pytest-httpx 补上了这个漏洞。根据其文档，只要有已注册的响应从未被请求，测试就会在 teardown 阶段失败。

默认情况下，对于没有匹配任何已注册响应的请求，pytest-httpx 还会立即抛出 `httpx.TimeoutException`，测试因此无法悄悄访问真实网络。Redowan Delowar 还提到了 respx，这个库能在测试期间拦截 httpx 请求并返回预设响应。两者都会增加一个依赖；对于第一周写的小客户端，内置的 `MockTransport` 就够用了。

## 常见错误

最常见的错误是在每个方法或每次循环中新建一个 `httpx.Client`。这违背了 httpx 文档的建议，`base_url` 和超时也会散落各处，切换环境或调整超时就得改很多地方。

第二个是捕获笼统的 `Exception` 然后返回 `None`。这样客户端会把 `ValidationError` 和 `HTTPStatusError` 一并吞掉，你会花上一个下午琢磨仪表盘为什么是空的。

第三个是在还没见过真实数据的第一天，就把模型定得过于严格。先用 staging 上的几个真实 payload 跑一遍客户端，再逐步收紧模型。

## 这在客户现场有什么用

部署一开始，就尽早写好这个客户端，因为它决定了日后错误会在哪里暴露。

如果客户不打招呼就改了 schema，`ValidationError` 测试和客户端的错误日志能让你直接指出问题：“从昨天发版起，`total` 字段就没有了”。

离线测试套件还能让你在尚未拿到 VPN 权限或凭证、或客户 staging 宕机时，照常推进工作。

如果你想应聘前线部署工程师（FDE）岗位，可以在作品集里放一个这样的仓库：为某个公开 API 编写的类型化客户端，测试覆盖全部三种结果。简历上写“带离线测试的类型化客户端，覆盖坏 payload 和 4xx 状态码”，比写“有 API 集成经验”更有说服力。

客户的系统会不断变化。你能掌控的是错误在哪里暴露，而最好的位置就是客户端入口。

**本周动手试试:**

- 挑一个目前以原始 dict 方式使用的端点，为它写一个 Pydantic 模型，再加一个 payload 缺字段的 MockTransport 测试。
- 找出现有代码中调用 httpx.get() 或在循环里新建 Client 的地方，把它们合并为一个显式设置超时的共享客户端。
- 在一个草稿仓库里安装 pytest-httpx，看看已注册的响应从未被请求时，测试是如何失败的。

## 信源

- [Transports - HTTPX](https://www.python-httpx.org/advanced/transports/)

- [Models - Pydantic Validation](https://pydantic.dev/docs/validation/latest/concepts/models/)

- [Error Handling - Pydantic Validation](https://pydantic.dev/docs/validation/latest/errors/errors/)

- [Timeouts - HTTPX](https://www.python-httpx.org/advanced/timeouts/)

- [QuickStart - HTTPX](https://www.python-httpx.org/quickstart/)

- [Clients - HTTPX](https://www.python-httpx.org/advanced/clients/)

- [pytest_httpx | pytest fixture to mock HTTPX](https://colin-b.github.io/pytest_httpx/)

- [How to use fixtures - pytest documentation](https://docs.pytest.org/en/stable/how-to/fixtures.html)

- [Don’t mock Python’s HTTPX](https://www.b-list.org/weblog/2023/dec/08/mock-python-httpx/)

- [Shades of testing HTTP requests in Python](https://rednafi.com/python/testing-http-requests/)
