İç içe geçmiş ve karmaşık istek gövdelerini nasıl modellersiniz?

Question

Accepted Answer

Pydantic modelleri **iç içe geçebilir** — bir model alanı başka bir model, model listesi veya karmaşık türler olabilir — FastAPI'nin derin yapılı JSON (nesneler içinde nesneler, nesneler dizileri) doğrulamasını otomatik olarak yapmasını sağlar.

## İç içe geçmiş modeller

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

Başka bir model olarak yazılan bir model alanı (veya `list[Model]`) özyinelemeli olarak doğrulanır — iç içe geçmiş nesneler ve nesneler dizileri tümü şemalarına karşı otomatik olarak kontrol edilir.

## Karmaşık ve özel türler

```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 zengin türleri işler: enumlar (izin verilen değerlerle sınırlandır), `datetime` (ISO dizelerini ayrıştır), `HttpUrl`/`EmailStr` (format doğrulaması) ve yazılmış sözlükler/tupllar — tümü otomatik olarak doğrulanır.

## Genel / yeniden kullanılabilir sarmalayıcılar

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

## Neden önemli

Gerçek dünya API'leri nadiren düz verilerle ilgilenir — karmaşık, iç içe yapılar ile işlerler (adresi ve siparişlerin listesi olan kullanıcı, satır öğeleri olan sipariş, yapılandırma nesneleri) ve Pydantic'in **model iç içe geçme** yeteneği bu derin yapılı istek gövdelerini doğrulamayı çok kolaylaştırır.

Bir model alanının başka bir model, model listesi veya zengin tür olabileceğini anlamak — ve FastAPI'nin **tüm iç içe yapıyı özyinelemeli olarak ve otomatik olarak doğruladığını** anlamak — gerçekçi, karmaşık giriş güvenli bir şekilde kabul eden API'ler oluşturmak için önemlidir.

Zengin tür desteği (sınırlı değerler için enumlar, `datetime` ayrıştırması, `HttpUrl`/`EmailStr` format doğrulaması, yazılan koleksiyonlar) karmaşık verilerin manuel kontrol olmadan doğru olmasını sağlar.

İç içe geçmiş ve karmaşık gövdeleri (sayfalama gibi şeyler için yeniden kullanılabilir genel sarmalayıcılar) modellemesini bilmek — gerçek uygulamaların gerektirdiği yapılandırılmış veriler ile işleyen API'ler oluşturmak için pratik bilgidir; tam doğrulama otomatik olarak sağlanır — bu FastAPI'nin Pydantic tabanlı tasarımının temel güçlerinden biridir.