Как моделировать вложенные и сложные тела запросов?

Question

Accepted Answer

Модели Pydantic могут **вкладываться** — поле модели может само быть другой моделью, списком моделей или сложными типами — позволяя FastAPI автоматически валидировать глубоко структурированный JSON (объекты внутри объектов, массивы объектов).

## Вложенные модели

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

Поле модели, типизированное как другая модель (или `list[Model]`), валидируется рекурсивно — вложенные объекты и массивы объектов проверяются по их схемам автоматически.

## Сложные и специальные типы

```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 обрабатывает богатые типы: enums (ограничение допустимыми значениями), `datetime` (парсинг ISO строк), `HttpUrl`/`EmailStr` (валидация формата) и типизированные dict/tuple — все валидируются автоматически.

## Универсальные / переиспользуемые обёртки

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

## Почему это важно

Реальные API редко работают с плоскими данными — они обрабатывают сложные, вложенные структуры (пользователь с адресом и списком заказов, заказ со строками позиций, объекты конфигурации), и возможность Pydantic **вкладывать модели** делает валидацию этих глубоко структурированных тел запросов простой.

Понимание того, что поле модели может быть другой моделью, списком моделей или богатым типом — и что FastAPI **валидирует всю вложенную структуру рекурсивно и автоматически** — важно для построения API, которые безопасно принимают реалистичные, сложные входные данные.

Поддержка богатых типов (enums для ограниченных значений, парсинг `datetime`, валидация формата `HttpUrl`/`EmailStr`, типизированные коллекции) дополнительно гарантирует корректность сложных данных без ручных проверок.

Знание того, как моделировать вложенные и сложные тела (и переиспользуемые универсальные обёртки для таких вещей, как пагинация), — это практическое знание для построения API, которые обрабатывают структурированные данные, которые требуют реальные приложения, с полной валидацией, предоставляемой автоматически — ключная сила архитектуры FastAPI на основе Pydantic.