Cum modelezi corpurile de cereri imbricate și complexe?

Question

Accepted Answer

Modelele Pydantic pot fi **imbricate** — un câmp al unui model poate fi el însuși un alt model, o listă de modele, sau tipuri complexe — permițând FastAPI să valideze automat JSON-ul profund structurat (obiecte în obiecte, tablouri de obiecte).

## Modele imbricate

```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"] }
```

Un câmp model tipizat ca alt model (sau `list[Model]`) este validat recursiv — obiectele imbricate și tablourile de obiecte sunt toate verificate împotriva schemelor lor automat.

## Tipuri complexe și speciale

```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 gestionează tipuri bogate: enumerări (restricție la valori permise), `datetime` (parsează șiruri ISO), `HttpUrl`/`EmailStr` (validare format), și dicționare tipizate/tupluri — toate validate automat.

## Wrappere generice / reutilizabile

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

## De ce conteaza

API-urile din lumea reală rar se ocupă cu date plate — acestea gestionează structuri complexe și imbricate (un utilizator cu o adresă și o listă de comenzi, o comandă cu articole de linie, obiecte de configurare), iar capacitatea Pydantic de a **imbrica modele** face validarea acestor corpuri de cereri profund structurate ușoară.

Înțelegerea că un câmp model poate fi un alt model, o listă de modele, sau un tip bogat — și că FastAPI **validează întreaga structură imbricate recursiv** și automat — este importantă pentru construirea API-urilor care acceptă intrări realiste și complexe în siguranță.

Sprijinul pentru tipuri bogate (enumerări pentru valori constrânse, parsare `datetime`, validare format `HttpUrl`/`EmailStr`, colecții tipizate) asigură în continuare că datele complexe sunt corecte fără verificări manuale.

Cunoașterea cum să modelezi corpuri imbricate și complexe (și wrappere generice reutilizabile pentru lucruri cum ar fi paginația) este cunoaștere practică pentru construirea API-urilor care gestionează datele structurate pe care le necesită aplicațiile reale, cu validare completă furnizată automat — un punct forte al design-ului bazat pe Pydantic al FastAPI.