Jak modelujete vnořené a složité těla požadavků?

Question

Accepted Answer

Pydantic modely mohou být **vnořeny** — pole modelu může být jiný model, seznam modelů nebo složité typy — což umožňuje FastAPI automaticky ověřovat hluboce strukturovaný JSON (objekty v objektech, pole objektů).

## Vnořené modely

```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 zapsané jako další model (nebo `list[Model]`) se ověřuje rekurzivně — vnořené objekty a pole objektů se všechny automaticky kontrolují proti jejich schématům.

## Složité a speciální typy

```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 zvládá bohaté typy: enums (omezit na povolené hodnoty), `datetime` (analýza ISO řetězců), `HttpUrl`/`EmailStr` (ověření formátu) a typované dicty/tuple — všechny jsou automaticky ověřovány.

## Obecné / opakovaně použitelné obálky

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

## Proč je to důležité

API v reálném světě se zřídka zabývají plochými daty — práce s komplexními, vnořenými strukturami (uživatel s adresou a seznamem objednávek, objednávka s položkami řádku, objekty konfigurace), a schopnost Pydanticu **vnořit modely** činí ověření hluboce strukturovaných těl požadavků bez námahy.

Porozumění tomu, že pole modelu může být jiný model, seznam modelů nebo bohatý typ — a že FastAPI **ověřuje celou vnořenou strukturu rekurzivně a automaticky** — je důležité pro vytváření rozhraní API, která bezpečně přijímají realistické, komplexní vstupy.

Podpora bohatých typů (enums pro omezené hodnoty, analýza `datetime`, ověření formátu `HttpUrl`/`EmailStr`, typované kolekce) dále zajišťuje, aby byla komplexní data správná bez ručních kontrol.

Vnímání modelování vnořených a složitých těl (a opakovaně použitelných obecných obalek pro věci jako stránkování) je praktické znalosti pro vytváření rozhraní API, která zpracovávají strukturovaná data, která vyžadují skutečné aplikace, s plným ověřením poskytovaným automaticky — klíčová síla Pydanticu založeného designu FastAPI.