Как писать собственную валидацию в Pydantic?

Question

Accepted Answer

Помимо встроенных ограничений, Pydantic позволяет вам писать **собственную логику валидации** с помощью field validators (валидируют одно поле) и model validators (валидируют несколько полей) — для правил, которые простые ограничения выразить не могут. (Синтаксис для Pydantic v2.)

## Field validators — валидация и трансформация одного поля

```python
from pydantic import BaseModel, field_validator

class User(BaseModel):
    username: str
    password: str

@field_validator("username")
    @classmethod
    def username_alphanumeric(cls, v: str) -> str:
        if not v.isalnum():
            raise ValueError("username must be alphanumeric")   # → a 422 error
        return v.lower()                                         # can also TRANSFORM the value
```

`@field_validator` запускает собственную логику на поле: поднимите `ValueError` чтобы отклонить некорректный ввод (FastAPI превратит это в чистый 422), или верните трансформированное значение (например, приведение к нижнему регистру).

## Model validators — кросс-полевая валидация

```python
from pydantic import model_validator

class SignupForm(BaseModel):
    password: str
    confirm_password: str

@model_validator(mode="after")
    def passwords_match(self):
        if self.password != self.confirm_password:    # compare MULTIPLE fields
            raise ValueError("passwords do not match")
        return self
```

`@model_validator(mode="after")` запускается после валидации всех полей, с доступом ко всей модели — используется для правил, которые включают **несколько полей** (например, проверка совпадения паролей, или что дата начала предшествует дате окончания).

## Встроенной валидации часто хватает в начале

```python
class Product(BaseModel):
    price: float = Field(gt=0)          # use Field constraints for simple rules
    sku: str = Field(pattern=r"^[A-Z]{3}-\d+$")
    email: EmailStr                      # specialized types for formats
# reach for custom validators only when constraints/types can't express the rule
```

Предпочитайте ограничения `Field` и специализированные типы для простых правил; используйте собственные валидаторы для реальной бизнес-логики.

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

Собственная валидация Pydantic важна для enforcement бизнес-правил, которые выходят за рамки простых проверок типов и ограничений — и поскольку валидация критична для **безопасности и целостности данных**, возможность выражать любое правило ценна. **Field validators** обрабатывают логику одного поля (проверки пользовательского формата, нормализация/трансформация), а **model validators** обрабатывают частую необходимость в **кросс-полевой валидации** (совпадение паролей, диапазоны дат, условные требования), которые правила на уровне полей выразить не могут.

Валидаторы интегрируются беспроблемно с FastAPI — поднятый `ValueError` автоматически становится чистым 422 ответом.

Понимание когда использовать встроенные ограничения/типы (для простых правил) versus собственные валидаторы (для реальной бизнес-логики), и чем field validators отличаются от model validators, позволяет вам гарантировать что входящие данные полностью удовлетворяют требованиям вашего приложения, делая это важным знанием для построения надёжных, корректных API.