Kako modelirate ugnezdene in kompleksne telesa zahtevkov?

Question

Accepted Answer

Pydantic modeli se lahko **ugnezdujejo** — polje modela je lahko sam drugi model, seznam modelov ali kompleksni tipi — kar FastAPI-ju omogoča avtomatsko preverjanje globoko strukturiranega JSON-a (objekti v objektih, nizi objektov).

## Ugnezdeni modeli

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

Polje modela, tipizirano kot drug model (ali `list[Model]`), se preverja rekurzivno — ugnezdeni objekti in nizi objektov se vsi samodejno preverjajo glede na njihove sheme.

## Kompleksni in posebni tipi

```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 obravnava bogate tipe: enume (omejitev na dovoljene vrednosti), `datetime` (razčlenjevanje ISO nizov), `HttpUrl`/`EmailStr` (preverjanje oblike) in tipizirane slovarje/tuple-e — vse se samodejno preveri.

## Splošni / ponovno uporabni oblikovci

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

## Zakaj je to pomembno

Ressični API-ji se redko bavijo s ploščatimi podatki — obravnavajo kompleksne, ugnezdene strukture (uporabnika z naslovom in seznamom naročil, naročilo s postavkami, objekti konfiguracije), in Pydantičeva sposobnost **ugnezdovanja modelov** naredi preverjanje teh globoko strukturiranih teles zahtevkov brezbolečno.

Razumevanje, da je polje modela lahko drug model, seznam modelov ali bogat tip — in da FastAPI **rekurzivno in samodejno preverja celotno ugnezdeno strukturo** — je pomembno za gradnjo API-jev, ki varno sprejemajo realistične, kompleksne vhode.

Podpora bogatih tipov (enumi za omejene vrednosti, razčlenjevanje `datetime`, preverjanje oblike `HttpUrl`/`EmailStr`, tipizirane zbirke) dodatno zagotavlja, da so kompleksni podatki pravilni brez ročnih preverjanj.

Znanje, kako modelirati ugnezdena in kompleksna telesa (in ponovno uporabne splošne oblikovce za stvari, kot sta paginacija), je praktično znanje za gradnjo API-jev, ki obravnavajo strukturirane podatke, ki jih zahtevajo pravi programi, s popolnim avtomatskim preverjanjem — ključna moč Pydantičnega dizajna FastAPI-ja.