Jak modelujesz zagnieżdżone i złożone ciała żądań?

Question

Accepted Answer

Modele Pydantic mogą być **zagnieżdżane** — pole modelu może być samo innym modelem, listą modeli lub typami złożonymi — pozwalając FastAPI na automatyczne walidowanie głęboko ustrukturyzowanego JSON (obiekty w obiektach, tablice obiektów).

## Modele zagnieżdżone

```python
from pydantic import BaseModel

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

class User(BaseModel):
    name: str
    address: Address                    # a NESTED model
    tags: list[str] = []                # a list of strings
    addresses: list[Address] = []       # a list of NESTED models

@app.post("/users")
def create(user: User):                  # validates the WHOLE nested structure
    return user
```

```json
// FastAPI validates this entire structure, including the nested address:
{ "name": "Ann",
  "address": { "street": "1 Main", "city": "NY", "zip": "10001" },
  "tags": ["vip"] }
```

Pole modelu typizowane jako inny model (lub `list[Model]`) jest walidowane rekurencyjnie — zagnieżdżone obiekty i tablice obiektów są wszystkie sprawdzane względem ich schematów automatycznie.

## Typy złożone i specjalne

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

class Status(str, Enum):                 # enums constrain to allowed values
    active = "active"
    inactive = "inactive"

class Item(BaseModel):
    url: HttpUrl                          # validates URL format
    email: EmailStr                       # validates email format
    created: datetime                     # parses ISO 8601 strings → datetime
    status: Status                        # must be one of the enum values
    metadata: dict[str, int]              # typed dict
    coordinates: tuple[float, float]      # typed tuple
```

Pydantic obsługuje bogate typy: enumeracje (ograniczenie do dozwolonych wartości), `datetime` (parsowanie stringów ISO), `HttpUrl`/`EmailStr` (walidacja formatu) i typizowane słowniki/krotki — wszystkie walidowane automatycznie.

## Generyczne / wielokrotnie używane wrappery

```python
from typing import Generic, TypeVar
T = TypeVar("T")
class Paginated(BaseModel, Generic[T]):   # a reusable generic response wrapper
    items: list[T]
    total: int
# Paginated[User] → { items: [User...], total: N }
```

## Dlaczego to ważne

Rzeczywiste API rzadko radzą sobie z płaskimi danymi — obsługują złożone, zagnieżdżone struktury (użytkownik z adresem i listą zamówień, zamówienie z pozycjami, obiekty konfiguracji), a zdolność Pydantic do **zagnieżdżania modeli** czyni walidowanie tych głęboko ustrukturyzowanych ciał żądań bezproblemową.

Zrozumienie, że pole modelu może być innym modelem, listą modeli lub bogatym typem — i że FastAPI **waliduje całą zagnieżdżoną strukturę rekurencyjnie i automatycznie** — jest ważne do budowania API, które przyjmuje realistyczne, złożone dane bezpiecznie.

Bogata obsługa typów (enumeracje dla wartości ograniczonych, parsowanie `datetime`, walidacja formatu `HttpUrl`/`EmailStr`, typizowane kolekcje) dodatkowo zapewnia, że złożone dane są poprawne bez ręcznych sprawdzeń.

Wiedzenie, jak modelować zagnieżdżone i złożone ciała (i wielokrotnie używane generyczne wrappery dla rzeczy takich jak paginacja) jest praktyczną wiedzą do budowania API, które obsługują ustrukturyzowane dane, które wymagają rzeczywiste aplikacje, z pełną walidacją zapewnianą automatycznie — kluczowa siła projektu FastAPI opartego na Pydantic.