Hogyan modellezi a beágyazott és összetett kérés testeket?

Question

Accepted Answer

A Pydantic modellek **beágyazhatók** — egy modell mező lehet egy másik modell, modellek listája vagy összetett típusok — lehetővé téve a FastAPI-nak, hogy automatikusan validálja a mélyen strukturált JSON-t (objektumok objektumokon belül, objektumtömbök).

## Beágyazott modellek

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

Egy másik modellként (vagy `list[Model]`-ként) típusozott modell mező rekurzívan kerül validálásra — a beágyazott objektumok és objektumtömbök mindegyike automatikusan ellenőrizésre kerül a sémáik alapján.

## Összetett és speciális típusok

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

A Pydantic gazdag típusokkal dolgozik: enums (engedélyezett értékekre korlátozza), `datetime` (ISO stringeket elemez), `HttpUrl`/`EmailStr` (formátum validáció), valamint typed dicts/tuples — mindegyik automatikusan validálva.

## Általános / újrafelhasználható wrapperek

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

## Miért fontos

A valódi API-k ritkán foglalkoznak egyszerű adatokkal — összetett, beágyazott struktúrákat kezelnek (felhasználó címmel és megrendelések listájával, megrendelés sortételekkel, konfigurációs objektumok), és a Pydantic **modellek beágyazásának** lehetősége tortolanul teszi e mélyen strukturált kéréstestek validálását.

Az a megértés, hogy egy modell mező lehet egy másik modell, modellek listája vagy gazdag típus — és hogy a FastAPI **a teljes beágyazott struktúrát rekurzívan** és automatikusan validálja — fontos az olyan API-k létrehozásához, amelyek valósságos, összetett bemeneteket fogadnak el biztonságosan.

A gazdag típusok támogatása (enumok korlátozott értékekhez, `datetime` elemzés, `HttpUrl`/`EmailStr` formátum validáció, típusított gyűjtemények) továbbá biztosítja, hogy az összetett adatok helyesek legyenek kézi ellenőrzés nélkül.

Annak ismerete, hogyan lehet beágyazott és összetett testeket modellezni (és újrafelhasználható általános wrappereket az oldalszámozáshoz hasonló dolgokhoz) praktikus tudás a valódi alkalmazások által igényelt strukturált adatokat kezelő API-k létrehozásához, teljes automatikus validálással — a FastAPI Pydantic-alapú tervének kulcserőssége.