Khi cần ghi log, lưu cache Redis hay đẩy dữ liệu sang BackgroundTasks, bạn không thể đưa thẳng Pydantic model hoặc datetime vào json.dumps() — nó sẽ ném TypeError. Hàm jsonable_encoder của FastAPI chuyển mọi kiểu dữ liệu đó thành dict, list, str và number tương thích JSON chỉ trong một dòng, và đây cũng là cách chính FastAPI dùng để tạo response. Dùng nó mỗi khi dữ liệu rời khỏi endpoint mà không đi qua response_model.
Vấn đề
Giả sử endpoint trả về thông tin user và bạn muốn ghi lại response vào log dạng JSON, hoặc cache vào Redis để lần sau khỏi query database. Cách tự nhiên nhất là gọi model_dump() rồi json.dumps(), nhưng model_dump() ở chế độ mặc định vẫn giữ nguyên datetime và Decimal. Kết quả là json.dumps() dừng ngay với lỗi TypeError: Object of type datetime is not JSON serializable — và toàn bộ đoạn log hay cache của bạn không chạy được.
Đoạn code dưới đây tái hiện đúng lỗi này:
import jsonfrom datetime import datetimefrom decimal import Decimalfrom pydantic import BaseModelclass UserOut(BaseModel): id: int name: str created_at: datetime balance: Decimaluser = UserOut( id=1, name="Linh", created_at=datetime(2026, 11, 18, 14, 0, 0), balance=Decimal("150000.50"),)json.dumps(user.model_dump())# TypeError: Object of type datetime is not JSON serializable
Giải pháp
Chỉ cần một dòng jsonable_encoder là xong. Hàm này nhận bất cứ thứ gì — Pydantic model, datetime, Decimal, Enum, UUID — và trả về cấu trúc chỉ gồm kiểu JSON-safe. Ví dụ dưới đây encode một model UserOut chứa đủ các kiểu khó nhằn nhất:
import jsonfrom fastapi.encoders import jsonable_encoderdata = jsonable_encoder(user)print(data)# {'id': 1, 'name': 'Linh',# 'created_at': '2026-11-18T14:00:00',# 'balance': '150000.50'}print(json.dumps(data)) # chạy được, sẵn sàng ghi log hay cache
Kết quả là một dict thuần: datetime thành chuỗi ISO 8601, Enum thành giá trị chuỗi, còn Decimal trong model thành chuỗi để giữ chính xác số tiền — tránh sai số float. Với Decimal rời rạc ngoài model, encoder trả về số float. Muốn định dạng ngày theo ý mình, truyền custom_encoder như ví dụ thứ hai.
Tham số exclude_unset=True chỉ lấy đúng field client đã gửi trong model PATCH — tiện để ghi log thay đổi hoặc cập nhật một phần mà không ghi đè field khác bằng None:
class PatchUser(BaseModel): name: str | None = None balance: Decimal | None = Nonepatch = PatchUser(name="Linh")jsonable_encoder(patch, exclude_unset=True)# {'name': 'Linh'} — balance chưa gửi nên không bị ghi đèjsonable_encoder( datetime(2026, 11, 18, 14, 0, 0), custom_encoder={datetime: lambda v: v.strftime("%d/%m/%Y %H:%M")},)# '18/11/2026 14:00'
Một lưu ý quan trọng: đừng gọi jsonable_encoder trong endpoint chỉ để trả response — FastAPI đã tự encode khi áp response_model. Hàm này dành cho dữ liệu đi ra ngoài response: log, cache, queue và BackgroundTasks.
Áp dụng vào dự án của bạn
Trong dự án thật, chỗ dùng jsonable_encoder nhiều nhất là ba nơi: cache response vào Redis bằng json.dumps(jsonable_encoder(data)) với TTL vài phút; ghi log request/response dạng JSON để tra cứu sau này; và truyền dữ liệu đã encode vào BackgroundTasks, vì task nền nhận dict JSON-safe thì không lo datetime gây lỗi giữa chừng. Bắt đầu từ endpoint hay cache nhất của bạn — thường chỉ một dòng là lỗi biến mất.
Bài viết liên quan
- FastAPI: validate dữ liệu đầu vào chuẩn chỉnh bằng Pydantic Field và validator tùy chỉnh
- FastAPI: chặn rò rỉ password trong response bằng response_model trong 5 phút
- FastAPI: quản lý DB session an toàn bằng dependency yield trong 5 phút
Câu hỏi thường gặp
jsonable_encoder khác gì model_dump(mode=”json”)?
Với Pydantic model, hai cách cho kết quả gần như giống nhau. Điểm mạnh của jsonable_encoder là nó xử lý được cả kiểu dữ liệu không phải model — datetime, Decimal, Enum, UUID hay dataclass — nên dùng được cho mọi thứ bạn muốn đưa thành JSON.
Decimal sau khi encode ra số hay chuỗi?
Tùy vị trí: Decimal đứng một mình thành số float, còn trong Pydantic model thành chuỗi để không mất chính xác. Với số tiền, chuỗi an toàn hơn; phía nhận dùng Decimal(chuỗi) để đổi lại.
Có nên dùng jsonable_encoder thay response_model trong endpoint?
Không. FastAPI đã tự encode response theo response_model, gọi thêm một lần nữa chỉ tốn công. Chỉ dùng jsonable_encoder khi dữ liệu rời khỏi response — ghi log, lưu cache, đẩy queue hoặc truyền vào BackgroundTasks.
custom_encoder dùng khi nào?
Khi định dạng mặc định không hợp ý bạn — ví dụ muốn ngày hiển thị dd/mm/yyyy thay vì ISO 8601, hoặc muốn UUID viết hoa. Truyền một dict ánh xạ kiểu dữ liệu sang hàm định dạng, encoder sẽ áp dụng cho mọi giá trị thuộc kiểu đó.
💬 Bạn đã thử cách này trong dự án của mình chưa? Nếu gặp lỗi hoặc có cách làm gọn hơn, để lại bình luận bên dưới — mình đọc hết và sẽ bổ sung những ý hay vào bài.
Nguồn tham khảo
- FastAPI — JSON Compatible Encoder: https://fastapi.tiangolo.com/tutorial/encoder/
- Pydantic — Serialization: https://docs.pydantic.dev/latest/concepts/serialization/
