Kaip modeliuoti įdėtus ir sudėtingus užklausos tekstus?

Question

Accepted Answer

Pydantic modeliai gali būti **įdėti** — modelio laukas gali būti kitas modelis, modelių sąrašas arba sudėtingos rūšys — leidžiant FastAPI automatiškai patikrinti giliai struktūrizuotą JSON (objektus objektuose, objektų masyvus).

## Įdėti modeliai

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

Modelio laukas, sudarintas kitu modeliu (arba `list[Model]`) patikrinamas rekursyviai — įdėti objektai ir objektų masyvai visi automatiškai tikrinami pagal jų schemas.

## Sudėtingos ir specialios rūšys

```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 tvarko turtingas rūšis: enum (apriboti iki leidžiamų reikšmių), `datetime` (analizuoti ISO eilutes), `HttpUrl`/`EmailStr` (formato tikrinimas) ir įvesties dict/tuples — visi automatiškai tikrinami.

## Bendrieji / pakartotinai naudojami apvalkalai

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

## Kodėl tai svarbu

Tikrojo pasaulio API retai susiduria su plokščiais duomenimis — jie tvarko sudėtingus, įdėtus struktūrus (vartotojas su adresu ir užsakymų sąrašu, užsakymas su eilučių elementais, konfigūracijos objektai), o Pydantic galimybė **modelius įdėti** daro šių giliai struktūrizuotų užklausos tekstų patikrinimą be pastangų.

Supratimas, kad modelio laukas gali būti kitas modelis, modelių sąrašas arba turtinga rūšis — ir kad FastAPI **rekursyviai** ir **automatiškai patikrina visą įdėtą struktūrą** — yra svarbus kuriant API, priimančius realistiškas, sudėtingas įvestis saugiai.

Turtingų rūšių palaikymas (enum susietos reikšmės, `datetime` analizavimas, `HttpUrl`/`EmailStr` formato tikrinimas, įvesti kolekcijai) toliau užtikrina, kad sudėtingi duomenys būtų teisingi be rankinio patikrinimo.

Žinojimas, kaip modeliuoti įdėtus ir sudėtingus tekstus (ir pakartotinai naudojamus bendruosius apvalkus tokiems dalykams kaip puslapiavimas) yra praktinis žinojimas kuriant API, kurie tvarko struktūrizuotus duomenis, kuriuos reikalauja tikros programos, su visišku automatiškai pateiktu patikrinmu — tai yra pagrindinė FastAPI Pydantic pagrindu pagrįsto dizaino stiprybė.