在客户端拦住客户的坏 JSON,再离线测试
只替换传输层,同一个客户端既能调用真实 API,也能离线跑测试,代码一行不改。
要点速览
- 按 httpx 文档的建议,客户端内部只保留一个 httpx.Client;设置 base_url 让调用更简洁;超时由自己决定,不要依赖默认的 5 秒。
- 用 Pydantic 校验响应:坏 payload 会直接在客户端抛出 ValidationError,错误信息会指出出问题的字段。
- 让客户端从外部接收 transport。这样借助 MockTransport,测试就能完全离线运行,代码无需改动。
进驻客户现场的第一周,接触最多的往往是对方的内部 API:文档不全,响应慢,还时不时返回与描述不符的 JSON。如果代码里到处都是 resp.json()["total"],只要缺一个字段,演示就会崩。而堆栈信息指向的,是埋在三层之下的某一行。
本指南教你用 httpx 和 Pydantic 写一个小巧的类型化 Python 客户端,再配一套不需要网络的测试,避开这个坑。示例使用一个假想的订单 API,它有一个 /orders/{id} 端点。订单 API 是虚构的,但文中用到的每个函数和类都出自 httpx、Pydantic 和 pytest 的官方文档。
你需要 Python 3、一个 virtualenv,再花几分钟做准备:
pip install httpx pydantic pytest
第 1 步:把数据契约写成模型
调用网络之前,先写下你认为 API 会返回什么。这个模型就是你的代码与客户系统之间的契约。
# 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,并在所有请求中复用。
# 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 对象的依赖,省去很多麻烦。
# 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 错误。每种都需要单独的测试。
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 集成经验”更有说服力。
客户的系统会不断变化。你能掌控的是错误在哪里暴露,而最好的位置就是客户端入口。
这篇文章对你有帮助吗?
感谢你的反馈!
10 个信源
- Transports - HTTPX
- Models - Pydantic Validation
- Error Handling - Pydantic Validation
- Timeouts - HTTPX
- QuickStart - HTTPX
- Clients - HTTPX
- pytest_httpx | pytest fixture to mock HTTPX
- How to use fixtures - pytest documentation
- Don’t mock Python’s HTTPX · 2023-12-08
- Shades of testing HTTP requests in Python · 2024-09-02