Что такое Pydantic модели в FastAPI?

Question

Accepted Answer

**Pydantic модели** — это классы (наследующие `BaseModel`), которые определяют **структуру, типы данных и правила валидации**. FastAPI использует их везде — для тел запросов, форм ответов и настроек — делая их сердцем своего типо-ориентированного дизайна.

## Определение модели

```python
from pydantic import BaseModel, EmailStr, Field

class User(BaseModel):
    name: str
    email: EmailStr                          # validates email format
    age: int = Field(ge=0, le=120)            # constraint: 0 <= age <= 120
    is_active: bool = True                    # default value
    tags: list[str] = []                      # typed list with a default
```

Каждое поле объявляет тип и опциональные ограничения/значения по умолчанию. Pydantic валидирует данные по этому определению и преобразует типы где это имеет смысл.

## Автоматическая валидация и парсинг

```python
@app.post("/users")
def create_user(user: User):                  # FastAPI builds & validates a User from the body
    return user                               # already validated here
# valid JSON → a typed User object; invalid → automatic 422 with field-level errors
```

Когда используется как тип параметра, FastAPI парсит JSON тело запроса в модель, **валидируя** каждое поле и возвращая структурированную ошибку 422, перечисляющую ровно то, что не так — всё автоматически.

## Что даёт вам Pydantic

```text
✓ Validation — type checks + constraints (lengths, ranges, formats), clear errors
✓ Parsing/coercion — "5" → 5, ISO string → datetime, etc.
✓ Serialization — model.model_dump() / model_dump_json() → dict/JSON
✓ Editor support — full autocomplete & type checking on model attributes
✓ Self-documenting — the model defines the schema used in the auto-generated docs
```

## Единый источник истины

```text
One Pydantic model drives: request validation, the response schema, the OpenAPI docs,
and typed access in your code → define the data shape ONCE.
```

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

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

Понимание их важно, потому что они обеспечивают автоматическую **валидацию** (критично для безопасности и надёжности — никогда не доверяя сырым входным данным), парсинг/приведение типов, сериализацию и поддержку редактора, всё из единого декларативного класса.

Они служат **единственным источником истины**: одна модель управляет валидацией запроса, формой ответа и автоматически генерируемой документацией.

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