Встроенные сообщения об ошибках и их кастомизация

Даже без дополнительной настройки, Pydantic автоматически генерирует сообщения об ошибках валидации. Это крутая особенность, позволяющая сэкономить время. Вот простой пример:

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

# Пытаемся создать модель с некорректными данными
data = {"name": "Alice", "age": "not_a_number"}
try:
    user = User(**data)
except Exception as e:
    print(e)

Вывод:

1 validation error for User
age
  value is not a valid integer (type=type_error.integer)

Как видим, ошибка довольно информативна: мы сразу понимаем, что поле age получило недопустимое значение. Сообщение включает в себя:

• Имя поля, которое вызвало ошибку.
• Краткое описание ошибки («не является целым числом»).
• Тип ошибки для дальнейшего анализа (type_error.integer).

Почему это полезно?

Такие сообщения позволяют быстро находить и исправлять ошибки как при разработке, так и при взаимодействии с API. Pydantic обрабатывает даже сложные структуры данных, предоставляя разработчику максимальную ясность.

---

Зачем кастомизировать сообщения об ошибках?

Хотя встроенные сообщения Pydantic отлично работают «из коробки», иногда они могут быть слишком техническими для конечного пользователя. Например, вместо информации вроде «value is not a valid integer» пользователю лучше показать что-то вроде: «Возраст должен быть числом». Это особенно важно для приложений, где взаимодействуют не только разработчики, но и пользователи с разным уровнем технической подготовки.

---

Как кастомизировать сообщения об ошибках?

Для настройки пользовательских сообщений в Pydantic используется параметр Field из модуля pydantic.

Давайте создадим модель с использованием Field, где определим более дружелюбные сообщения об ошибках:

from pydantic import BaseModel, Field

class User(BaseModel):
    name: str = Field(..., title="Имя пользователя", max_length=20, description="Пожалуйста, введите имя длиной до 20 символов.")
    age: int = Field(..., gt=0, lt=130, description="Возраст должен быть числом от 1 до 129.")

# Пробуем передать некорректные данные
data = {"name": "A very very long name that is not valid", "age": 200}
try:
    user = User(**data)
except Exception as e:
    print(e)

Вывод:

2 validation errors for User
name
  ensure this value has at most 20 characters (type=value_error.any_str.max_length; limit_value=20)
age
  ensure this value is less than 130 (type=value_error.number.not_lt; limit_value=130)

Совсем другое дело! Мы настроили ограничения (например, максимум 20 символов для поля name или числовой диапазон для age), а Pydantic автоматически добавил их в описание ошибок.

---

Кастомизация сообщений через валидаторы

Иногда вам может понадобиться задать настолько специфические правила, что стандартные инструменты валидации не справятся. В таких случаях на помощь приходит декоратор @validator.

Пример с кастомным валидатором

from pydantic import BaseModel, Field, field_validator

class User(BaseModel):
    name: str
    age: int = Field(..., ge=18)  # Можно сразу задать ограничение через Field

    @field_validator("age")
    @classmethod
    def check_age(cls, value):
        if value < 18:
            raise ValueError("Возраст должен быть не менее 18.")
        return value

# Пытаемся передать данные несовершеннолетнего
data = {"name": "John", "age": 16}
try:
    user = User(**data)
except Exception as e:
    print(e)

Вывод:

1 validation error for User
age
  Возраст должен быть не менее 18. (type=value_error)

Здесь мы создали полностью кастомное правило: для возрастного поля теперь мы можем задавать уникальную логику, например, проверку на совершеннолетие.

---

Практический пример: API с кастомными ошибками

Давайте попробуем интегрировать всё вышеперечисленное в эндпоинт FastAPI. Мы будем обрабатывать запросы на регистрацию пользователей, улучшая обратную связь через кастомные ошибки.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field, ValidationError

app = FastAPI()

class User(BaseModel):
    name: str = Field(..., max_length=20, description="Имя должно быть не длиннее 20 символов.")
    age: int = Field(..., gt=0, lt=130, description="Возраст должен быть в диапазоне от 1 до 129.")

@app.post("/register")
async def register_user(user: User):
    return {"message": f"Пользователь {user.name} успешно зарегистрирован!"}

# Запускаем и пробуем отправить неверные данные через curl или Postman

Если передать некорректные данные, вроде:

{
    "name": "A very very long name that definitely will not pass validation",
    "age": 150
}

Ответ будет таким:

{
    "detail": [
        {
            "loc": ["body", "name"],
            "msg": "ensure this value has at most 20 characters",
            "type": "value_error.any_str.max_length",
            "ctx": {"limit_value": 20}
        },
        {
            "loc": ["body", "age"],
            "msg": "ensure this value is less than 130",
            "type": "value_error.number.not_lt",
            "ctx": {"limit_value": 130}
        }
    ]
}

---

Глубокая настройка пользовательских сообщений

Если вы хотите добиться максимального контроля над обработкой ошибок, можно перехватывать исключения ValidationError и самостоятельно строить ответы.

from fastapi import FastAPI, Request
from pydantic import ValidationError

app = FastAPI()

@app.exception_handler(ValidationError)
async def validation_exception_handler(request: Request, exc: ValidationError):
    return JSONResponse(
        status_code=422,
        content={"detail": "Некорректные данные. Проверьте ввод!"}
    )

Теперь все валидационные ошибки будут возвращать единое сообщение "Некорректные данные. Проверьте ввод!".

---

Итог

Мы научились работать с встроенными и кастомными сообщениями об ошибках Pydantic, что поможет вам создавать более дружелюбные и понятные приложения. Используйте Field, Config и кастомные валидаторы, чтобы улучшить взаимодействие с пользователями. Теперь ваши API не только мощные и удобные, но и дружелюбные к людям — настоящая мечта любого разработчика.