Wie modellieren Sie verschachtelte und komplexe Request-Bodies?

Question

Accepted Answer

Pydantic-Modelle können **verschachtelt** werden — ein Modellfeld kann ein anderes Modell, eine Liste von Modellen oder komplexe Typen sein — und ermöglichen es FastAPI, tiefgreifend strukturiertes JSON (Objekte in Objekten, Arrays von Objekten) automatisch zu validieren.

## Verschachtelte Modelle

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

Ein als anderes Modell typisiertes Modellfeld (oder `list[Model]`) wird rekursiv validiert — verschachtelte Objekte und Arrays von Objekten werden alle automatisch gegen ihre Schemas überprüft.

## Komplexe und spezielle Typen

```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 verarbeitet reichhaltige Typen: enums (Einschränkung auf zulässige Werte), `datetime` (Parsing von ISO-Strings), `HttpUrl`/`EmailStr` (Formatvalidierung) und typisierte Dicts/Tuples — alle werden automatisch validiert.

## Generische / wiederverwendbare Wrapper

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

## Warum es wichtig ist

Real-world APIs behandeln selten flache Daten — sie handhaben komplexe, verschachtelte Strukturen (ein Benutzer mit einer Adresse und einer Liste von Bestellungen, eine Bestellung mit Zeilenelementen, Konfigurationsobjekten), und Pydantics Fähigkeit, **Modelle zu verschachteln**, macht die Validierung tief strukturierter Request-Bodies mühelos.

Das Verständnis, dass ein Modellfeld ein anderes Modell, eine Liste von Modellen oder ein reichhaltiger Typ sein kann — und dass FastAPI **die gesamte verschachtelte Struktur rekursiv und automatisch validiert** — ist wichtig für den Aufbau von APIs, die realistische, komplexe Eingaben sicher akzeptieren.

Die Unterstützung reicher Typen (enums für begrenzte Werte, `datetime`-Parsing, `HttpUrl`/`EmailStr`-Formatvalidierung, typisierte Sammlungen) stellt darüber hinaus sicher, dass komplexe Daten ohne manuelle Prüfungen korrekt sind.

Zu wissen, wie man verschachtelte und komplexe Bodies modelliert (und wiederverwendbare generische Wrapper für Dinge wie Pagination) ist praktisches Wissen für den Aufbau von APIs, die die strukturierten Daten verarbeiten, die echte Anwendungen erfordern, mit vollständiger automatisch bereitgestellter Validierung — eine Schlüsselstärke von FastAPIs Pydantic-basiertem Design.