Si modeloni trupat e kërkesave të gjitura dhe komplekse?

Question

Accepted Answer

Modelet Pydantic mund të **gjitohen** — një fushë e modelit mund të jetë vetë një model tjetër, një listë modelesh, ose lloje komplekse — duke lejuar FastAPI-n të validojë JSON-in thellësisht të strukturuar (objekte brenda objekteve, vargje objektesh) automatikisht.

## Modelet e gjitura

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

Një fushë e modelit e tipizuar si një model tjetër (ose `list[Model]`) validihet rekurzivisht — objektet e gjitura dhe vargjet e objekteve kontrollohes të gjitha kundrejt skemave të tyre automatikisht.

## Lloje komplekse dhe të veçanta

```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 trajton lloje të pasura: enum-e (kufizoni në vlera të lejuara), `datetime` (analizë stringjesh ISO), `HttpUrl`/`EmailStr` (validim formati), dhe tupla/fjalorë të tipizuara — të gjitha validuar automatikisht.

## Mbështjellës përgjithësuese / të rimëndshme

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

## Pse rëndëson

APIt-et e botës reale rrallë merren me të dhëna të sheshta — ato trajtonin struktura komplekse të gjitura (një përdorues me një adresë dhe një listë porosish, një porosi me artikuj rreshti, objekte konfigurimi), dhe aftësia e Pydantic-ut të **gjitohet modeleve** bën validimin e këtyre trupave të kërkesave thellësisht të strukturuara pa përpjekje.

Komprehensioni që një fushë e modelit mund të jetë një model tjetër, një listë modelesh, ose një lloj i pasur — dhe se FastAPI **validiton të gjithë strukturën e gjitur rekurzivisht** dhe automatikisht — është i rëndësishëm për ndërtimin e API-ve që pranojnë hyrje realistike dhe komplekse në mënyrë të sigurt.

Përkrahja e llojeve të pasura (enum-et për vlera të kufizuara, analizë `datetime`, validim formati `HttpUrl`/`EmailStr`, koleksione të tipizuara) siguron më tej se të dhëna komplekse janë korrekte pa kontrolle manuale.

Dija se si të modeloni trupat e gjitur dhe komplekse (dhe mbështjellës përgjithësuese të rimëndshme për gjëra si paginimi) është njohje praktike për ndërtimin e API-ve që trajtonin të dhëna të strukturuara që kërkojnë aplikacionet reale, me validim të plotë të siguruar automatikisht — një forcë kyçe e dizajnit të bazuar në Pydantic të FastAPI-t.