Kuinka mallinnat sisäkkäisiä ja monimutkaisia pyynnön kappaleita?

Question

Accepted Answer

Pydantic-mallit voivat **sisäkkäistyä** — mallokenttä voi olla toinen malli, malliluettelo tai monimutkaiset tyypit — joiden avulla FastAPI voi automaattisesti tarkistaa syvyydeltään strukturoitua JSON:ia (objekteja objektien sisällä, objektien taulukoita).

## Sisäkkäiset mallit

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

Toiseksi malliksi kirjoitettu mallokenttä (tai `list[Model]`) tarkistetaan rekursiivisesti — sisäkkäiset objektit ja objektitaulukot tarkistetaan kaikki automaattisesti niitä vastaan schemataaan.

## Monimutkaiset ja erityiset tyypit

```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 käsittelee rikkaita tyyppejä: enums (rajoita sallittuihin arvoihin), `datetime` (jäsennä ISO-merkkijonot), `HttpUrl`/`EmailStr` (muodon validointi) ja tyypitellyt dictsit/tuples — kaikki tarkistetaan automaattisesti.

## Yleiset / uudelleen käytettävät wrapperit

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

## Miksi se on tärkeää

Todellisen maailman API:t käsittelevät harvoin tasaisia tietoja — ne käsittelevät monimutkaisia, sisäkkäisiä rakenteita (käyttäjä osoitteella ja tilausluettelolla, tilaus rivikohteilla, konfiguraation objekteilla), ja Pydantican kyvyt **sisäkkäistyä malleille** tekevät syvyydeltään strukturoitujen pyynnön kappaleiden validoinnin vaivattomaksi.

Ymmärryksen mukaan mallokenttä voi olla toinen malli, malliluettelo tai rikas tyyppi — ja että FastAPI **validoi koko sisäkkäisen rakenteen rekursiivisesti ja automaattisesti** — on tärkeää rakentaa API:ita, jotka hyväksyvät realistisia, monimutkaisia syötteitä turvallisesti.

Rikkaat tyypit tuki (enumit rajoitetuille arvoille, `datetime`-jäsentäminen, `HttpUrl`/`EmailStr`-muodon validointi, tyypitellyt kokoelmat) varmistaa lisäksi, että monimutkaiset tiedot ovat oikein ilman manuaalisia tarkistuksia.

Tietää, kuinka sisäkkäisiä ja monimutkaisia kappaleita mallinnetaan (ja uudelleen käytettäviä yleisiä wrappereja asioille, kuten sivutus), on käytännön tietoa API:iden rakentamiseen, jotka käsittelevät strukturoituja tietoja, joita oikeat sovellukset vaativat, täydellä automaattisesti toimitetulla validoinnilla — FastAPI:n Pydantic-pohjaisesta suunnittelusta käsin avainvahvuus.