Viết client có kiểu cho API của khách mà test không cần mạng
Chỉ cần đổi transport, cùng một client vừa gọi API thật vừa chạy test offline mà không phải sửa code.
Tóm tắt nhanh
- Giữ đúng một httpx.Client trong client như tài liệu httpx khuyên, đặt base_url cho gọn và tự chọn timeout thay vì dựa vào mặc định 5 giây.
- Kiểm tra phản hồi bằng Pydantic: payload sai gây ValidationError ngay ở client, và lỗi nêu đúng tên trường có vấn đề.
- Cho client nhận transport từ bên ngoài. Khi đó MockTransport giúp test chạy hoàn toàn offline mà không phải sửa code.
Tuần đầu ở chỗ khách, thứ bạn chạm vào nhiều nhất thường là API nội bộ của họ: thiếu tài liệu, chậm, và thỉnh thoảng trả về JSON lệch với mô tả. Nếu code của bạn đọc resp.json()["total"] ở khắp nơi, chỉ cần một trường biến mất là demo hỏng. Lúc đó stack trace lại chỉ tới một dòng nằm sâu ba tầng bên trong.
Hướng dẫn này giúp bạn tránh tình huống đó bằng một client Python nhỏ, có kiểu, dùng httpx và Pydantic, kèm bộ test chạy không cần mạng. Bạn sẽ làm việc với một API đơn hàng giả định có endpoint /orders/{id}. API đơn hàng là giả định, nhưng mọi hàm và lớp được dùng đều có trong tài liệu chính thức của httpx, Pydantic và pytest.
Bạn cần Python 3, một virtualenv và vài phút cài đặt:
pip install httpx pydantic pytest
Bước 1: viết hợp đồng dữ liệu thành model
Trước khi gọi mạng, hãy ghi lại những gì bạn tin là API sẽ trả về. Model này chính là hợp đồng giữa code của bạn và hệ thống của khách.
# orders_client/models.py
from pydantic import BaseModel
class Order(BaseModel):
id: int
status: str
total: float
Theo tài liệu của Pydantic, hễ dữ liệu không khớp model là thư viện ném ValidationError. Ngược lại, khi validate thành công, Pydantic bảo đảm các trường của object khớp đúng kiểu đã khai báo. Client trong bài dựa vào bảo đảm này, nên code phía sau không còn phải tự hỏi total có tồn tại hay không.
Kiểm tra: trong REPL, gọi Order.model_validate_json('{"id": 1, "status": "new"}'). Bạn sẽ thấy ValidationError với một mục lỗi có type missing, thông báo Field required, và phần tử đầu của loc là total.
Bước 2: vì sao chỉ nên có một httpx.Client?
Nhiều người gọi thẳng httpx.get() trong từng hàm. Cách đó vẫn chạy, nhưng tài liệu httpx khuyên rõ: hễ làm gì hơn mức thử nghiệm, script dùng một lần hay prototype, hãy dùng một instance Client. Vì thế client cho API của khách nên giữ đúng một httpx.Client và dùng lại nó cho mọi request.
# 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 khách trả {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()
Đoạn code này có ba quyết định đáng chú ý. Quyết định đầu tiên nằm ở base_url: httpx gắn URL này vào trước mọi request, nên mỗi phương thức chỉ cần truyền path. Muốn chuyển từ staging sang production, bạn chỉ sửa một chuỗi.
Quyết định thứ hai là timeout. Mặc định httpx ném TimeoutException khi mạng im lặng quá 5 giây. Con số đó có thể quá ngắn với một báo cáo chạy lâu, hoặc quá dài với một endpoint lẽ ra phải trả lời ngay.
Ở đây timeout được ghi thẳng ra để người đọc code hiểu đây là một lựa chọn có chủ đích, không phải giá trị mặc định bị bỏ quên. Con số 10 giây chỉ để minh hoạ, còn giá trị thật thì hãy hỏi khách SLA của endpoint.
Quyết định cuối cùng là raise_for_status(). Hàm này biến mọi phản hồi ngoài nhóm 2xx thành HTTPStatusError, và lỗi đó mang theo cả request lẫn response. Client đổi nó thành CustomerApiError, nhờ vậy với lỗi HTTP, tầng trên bắt một lỗi của dự án thay vì phải biết tới lớp lỗi của httpx.
Cần nói rõ giới hạn của bản rút gọn này: ValidationError và httpx.TimeoutException vẫn đi thẳng lên người gọi. ValidationError được để nguyên có chủ đích, để test ở Bước 4 thấy rõ payload sai. Trong dự án thật, bạn có thể bọc nốt hai loại này thành lỗi riêng, khi đó tầng trên mới thật sự chỉ cần bắt lỗi của dự án.
Kiểm tra: get_order trả về Order chứ không phải dict. Editor của bạn giờ đã gợi ý được .total.
Bước 3: tham số transport để làm gì?
Hãy để ý tham số transport=None trong hàm khởi tạo, vì đây là chỗ cho phép test chạy offline. Theo tài liệu httpx, MockTransport nhận một hàm handler, và hàm này ánh xạ từng request sang một response định sẵn. Không có request thật nào rời khỏi máy.
Cách nối vào cũng đơn giản, vì httpx.Client vốn nhận tham số transport: truyền httpx.MockTransport(handler) vào là xong. Code đang được test giữ nguyên, chỉ lớp transport bên dưới được thay.
James Bennett, trong bài “Don’t mock Python’s HTTPX”, khuyên đúng hướng này: dùng mock transport có sẵn của HTTPX thay vì mock chính HTTPX hay các thành phần bên trong nó, để bớt phụ thuộc vào đối tượng mock và tránh được nhiều rắc rối.
# 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.khach.example", transport=httpx.MockTransport(handler))
yield c
c.close()
Trong pytest, test function lấy fixture chỉ bằng cách khai báo nó làm tham số. Nhờ đó mọi test dùng chung một client chạy trên mock mà không phải lặp lại phần dựng.
Bước 4: test cả ba trường hợp, không chỉ trường hợp suôn sẻ
Một client gọi vào hệ thống của khách có ít nhất ba kết quả: dữ liệu đúng, dữ liệu sai hình dạng, và lỗi HTTP. Mỗi kết quả cần một test riêng.
def test_order_ok(client):
order = client.get_order(42)
assert order.total == 19.5
def test_payload_thieu_truong(client):
with pytest.raises(ValidationError):
client.get_order(7)
def test_404_thanh_loi_rieng(client):
with pytest.raises(CustomerApiError) as exc:
client.get_order(999)
assert exc.value.status_code == 404
Hãy xem kỹ đơn hàng 7. API trả mã 200, trông như thành công, nhưng thiếu total. Nếu không có model, lỗi chỉ lộ ra khi một hàm tính doanh thu ở đâu đó gặp KeyError.
Có model, get_order(7) dừng ngay với ValidationError, và mục lỗi nêu đích danh trường total kèm thông báo Field required. Bạn biết ngay trường nào hỏng, ở endpoint nào.
Kiểm tra: tắt Wi-Fi rồi chạy pytest -q. Cả ba test vẫn phải xanh.
Khi nào nên chuyển sang pytest-httpx?
Handler viết tay rất dễ hiểu, nhưng có một điểm mù: nếu bạn viết sẵn response cho một path mà code không bao giờ gọi tới, test vẫn xanh. pytest-httpx lấp lỗ hổng này. Theo tài liệu của nó, test sẽ thất bại lúc teardown nếu còn response đã đăng ký mà chưa được gửi ra.
Mặc định, pytest-httpx cũng ném ngay httpx.TimeoutException với mọi request không khớp response nào đã đăng ký, nên test không thể âm thầm gọi ra mạng thật. Redowan Delowar còn nhắc tới respx, thư viện chặn request của httpx trong lúc test và trả response dựng sẵn. Cả hai đều là thêm một dependency; với một client nhỏ trong tuần đầu, MockTransport có sẵn là đủ.
Những lỗi hay gặp
Lỗi phổ biến nhất là tạo httpx.Client mới trong mỗi phương thức hoặc mỗi vòng lặp. Làm vậy đi ngược lời khuyên của tài liệu httpx, và base_url cùng timeout bị rải ra nhiều nơi, nên đổi môi trường hay chỉnh timeout là phải sửa nhiều chỗ.
Lỗi thứ hai là bắt Exception chung chung rồi trả về None. Khi đó client nuốt mất cả ValidationError lẫn HTTPStatusError, và bạn sẽ mất một buổi chiều để tìm vì sao dashboard trống.
Lỗi thứ ba là siết model quá chặt ngay từ ngày đầu, khi chưa thấy dữ liệu thật. Hãy cho client chạy với vài payload thật lấy từ staging rồi mới siết model dần.
Ở chỗ khách, kỹ năng này giúp gì
Khi bắt đầu một deployment, nên viết client này càng sớm càng tốt, vì nó quyết định lỗi về sau sẽ lộ ra ở đâu.
Nếu khách đổi schema mà không báo, test ValidationError và log lỗi tại client giúp bạn chỉ thẳng vấn đề: “trường total đã biến mất từ bản phát hành hôm qua”.
Bộ test offline còn cho bạn làm việc được khi chưa có VPN, chưa có credential, hoặc khi staging của khách đang sập.
Nếu đang nhắm tới vị trí FDE, hãy đưa một repo như thế này vào portfolio: client có kiểu cho một API công khai, test bao phủ cả ba trường hợp. Trong CV, ghi cụ thể “client có kiểu với test offline cho payload lỗi và mã 4xx” sẽ thuyết phục hơn “có kinh nghiệm tích hợp API”.
Hệ thống của khách sẽ còn thay đổi. Điều bạn kiểm soát được là lỗi sẽ lộ ra ở đâu, và chỗ tốt nhất là ngay tại client.
Bài này có hữu ích không?
Cảm ơn bạn đã góp ý!
10 nguồn
- 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