Làm thế nào để mô hình hóa request body lồng nhau và phức tạp?

Question

Accepted Answer

Pydantic model có thể **lồng nhau** — một field của model có thể chính là một model khác, một list các model, hoặc các kiểu phức tạp — cho phép FastAPI validate JSON có cấu trúc sâu (object trong object, mảng object) tự động.

## Model lồng nhau

```python
from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    zip: str

class User(BaseModel):
    name: str
    address: Address                    # một model LỒNG
    tags: list[str] = []                # một list các chuỗi
    addresses: list[Address] = []       # một list các model LỒNG

@app.post("/users")
def create(user: User):                  # validate TOÀN BỘ cấu trúc lồng
    return user
```

```json
// FastAPI validate toàn bộ cấu trúc này, bao gồm cả address lồng:
{ "name": "Ann",
  "address": { "street": "1 Main", "city": "NY", "zip": "10001" },
  "tags": ["vip"] }
```

Một field của model có kiểu là một model khác (hoặc `list[Model]`) được validate đệ quy — các object lồng và mảng object đều được kiểm tra theo schema của chúng tự động.

## Kiểu phức tạp và đặc biệt

```python
from pydantic import BaseModel, HttpUrl, EmailStr
from datetime import datetime
from enum import Enum

class Status(str, Enum):                 # enum giới hạn vào các giá trị cho phép
    active = "active"
    inactive = "inactive"

class Item(BaseModel):
    url: HttpUrl                          # validate định dạng URL
    email: EmailStr                       # validate định dạng email
    created: datetime                     # parse chuỗi ISO 8601 → datetime
    status: Status                        # phải là một trong các giá trị enum
    metadata: dict[str, int]              # dict có kiểu
    coordinates: tuple[float, float]      # tuple có kiểu
```

Pydantic xử lý các kiểu phong phú: enum (giới hạn vào giá trị cho phép), `datetime` (parse chuỗi ISO), `HttpUrl`/`EmailStr` (validate định dạng), và dict/tuple có kiểu — tất cả được validate tự động.

## Wrapper generic / tái sử dụng

```python
from typing import Generic, TypeVar
T = TypeVar("T")
class Paginated(BaseModel, Generic[T]):   # một response wrapper generic tái sử dụng
    items: list[T]
    total: int
# Paginated[User] → { items: [User...], total: N }
```

## Tại sao điều này quan trọng

API thực tế hiếm khi xử lý dữ liệu phẳng — chúng xử lý các cấu trúc phức tạp, lồng nhau (một user với một address và một list order, một order với line item, các object cấu hình), và khả năng **lồng model** của Pydantic khiến việc validate các request body có cấu trúc sâu này trở nên dễ dàng.

Hiểu rằng một field của model có thể là một model khác, một list các model, hoặc một kiểu phong phú — và rằng FastAPI **validate toàn bộ cấu trúc lồng một cách đệ quy** và tự động — quan trọng để xây dựng API chấp nhận input thực tế, phức tạp một cách an toàn.

Hỗ trợ kiểu phong phú (enum cho giá trị bị giới hạn, parse `datetime`, validate định dạng `HttpUrl`/`EmailStr`, các collection có kiểu) còn đảm bảo dữ liệu phức tạp đúng đắn mà không cần kiểm tra thủ công.

Biết cách mô hình hóa body lồng nhau và phức tạp (và các wrapper generic tái sử dụng cho những thứ như phân trang) là kiến thức thực tiễn để xây dựng API xử lý dữ liệu có cấu trúc mà ứng dụng thực yêu cầu, với validation đầy đủ được cung cấp tự động — một điểm mạnh then chốt của thiết kế dựa trên Pydantic của FastAPI.