# 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.

Bản gốc: https://fdetimes.net/vi/bach-khoa/thuc-hanh-client-python-httpx-pydantic-cho-api-khach/

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:

```bash
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.

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

```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 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.

```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.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.

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

**Điểm mấu chốt:** Dữ liệu sai của khách nên bị chặn ở cửa client, đừng để nó lọt vào logic nghiệp vụ.

## 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.

**Thử ngay tuần này:**

- Chọn một endpoint bạn đang gọi bằng dict thô, viết model Pydantic cho nó và thêm một test MockTransport với payload thiếu trường.
- Rà những chỗ gọi httpx.get() hoặc tạo Client mới trong vòng lặp ở code hiện tại, rồi gom chúng về một client dùng chung có timeout ghi rõ.
- Cài pytest-httpx vào một repo thử nghiệm và xem test thất bại thế nào khi có một response đã đăng ký mà không ai gọi tới.

## Nguồn

- [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/)
