Pydantic для новичка: проверяем JSON из API и показываем понятные ошибки

Pydantic превращает сырой словарь из JSON в объект с проверенными полями или в структурированный список ошибок. Соберём модель заказа на Pydantic 2, проверим пропущенное имя, отрицательную цену и неверное количество. Затем превратим технический ValidationError в сообщения, которые можно показать пользователю API.

Обычный dict принимает строку вместо числа и замечает проблему только глубже в программе. С Pydantic граница данных появляется сразу после json.loads. В этой статье вы соберёте валидатор заказа с полями name, price и quantity. Финальный результат можно проверить без догадок: правильный JSON даёт total=599.80, а три неверных поля возвращаются отдельными ошибками.

Как Pydantic проверяет JSON на границе программы

Входной JSON сначала превращается в словарь Python. Затем Order.model_validate сопоставляет ключи с аннотациями, применяет Field и дополнительный field_validator. Бизнес-код получает только Order, поэтому не повторяет проверки цены и количества. Для Pydantic держите этапы раздельно: ввод, проверка, основное действие и вывод. Такой маршрут позволяет остановиться в конкретной точке, увидеть фактические данные и исправить одну причину вместо случайной перестановки строк.

Ошибка останавливается у входа, а не всплывает как TypeError во время расчёта. У Pydantic каждый этап оставляет наблюдаемый след, поэтому следующий шаг начинается только после проверки предыдущего.

От входных данных до видимого результата. Бизнес-код получает только проверенный объект

Пишем модель заказа и выводим ошибки

Создайте проект командами uv init pydantic-lab и uv add pydantic. Сохраните код в main.py и запустите uv run python main.py. Пример использует API Pydantic 2: BaseModel, Field, field_validator и model_validate. Старый parse_obj из материалов по Pydantic 1 здесь не нужен.

import json
from decimal import Decimal

from pydantic import BaseModel, Field, ValidationError, field_validator


class Order(BaseModel):
    name: str = Field(min_length=2, max_length=40)
    price: Decimal = Field(gt=0, decimal_places=2)
    quantity: int = Field(ge=1, le=20)

    @field_validator("name")
    @classmethod
    def name_must_not_be_blank(cls, value: str) -> str:
        cleaned = value.strip()
        if not cleaned:
            raise ValueError("name cannot be blank")
        return cleaned

    @property
    def total(self) -> Decimal:
        return self.price * self.quantity


raw = '{"name":"Keyboard","price":"299.90","quantity":2}'

try:
    order = Order.model_validate(json.loads(raw))
    print(order.model_dump())
    print(f"total={order.total:.2f}")
except ValidationError as error:
    for item in error.errors():
        field = ".".join(map(str, item["loc"]))
        print(f"{field}: {item['msg']}")

Decimal выбран вместо float, чтобы учебный пример не накапливал двоичную погрешность в денежной сумме. Пример Pydantic специально ограничен одним пользовательским сценарием, чтобы назначение каждой строки оставалось видимым.

Что отличает устойчивый проект от случайного запуска. Контракт держит ограничения рядом с типами

Из чего состоит ValidationError в Pydantic 2

BaseModel читает аннотации один раз при создании класса и строит внутреннюю схему. Field добавляет ограничения поверх типа. При model_validate Pydantic собирает все найденные проблемы, а не останавливается на первой. Поле loc показывает путь, поэтому вложенная ошибка может выглядеть как items.0.price. Поле type удобно для машинной обработки, msg подходит для журнала, input помогает увидеть исходное значение. В ответе публичного API не стоит бездумно возвращать весь input: там может оказаться пароль или токен.

Pydantic может преобразовать строку "299.90" в Decimal, но это не значит, что нужно принимать любые преобразования. Для строгой границы используйте StrictInt, StrictStr или model_config. У значения по умолчанию есть отдельная ловушка: оно не всегда валидируется так же, как вход, пока не включена соответствующая настройка. Модели также умеют вложенные списки и JSON Schema, однако новичку полезнее сначала научиться читать errors(). Если ошибка не объяснима по loc и type, усложнять модель рано.

Ломаем входные данные и проверяем правила

Запустите валидный заказ. Затем по очереди удалите name, передайте price=-1, quantity="many" и имя из пробелов. После каждого запуска выпишите loc и type. Добавьте необязательное поле coupon: str | None = None и запретите код длиннее 12 символов. Последний шаг: создайте Cart с полем items: list[Order] и проверьте ошибку во втором элементе. Не исправляйте данные внутри except, сначала добейтесь точного сообщения.

Хорошая модель не угадывает намерение пользователя. Она принимает описанный формат и точно сообщает, где контракт нарушен. После этой проверки измените одно правило Pydantic и заранее запишите ожидаемый результат. Так копирование превращается в понимание.

Четыре проверки перед следующим шагом. Ошибку можно воспроизвести отдельным входом

Как применять Pydantic в настоящем API

В FastAPI модели Pydantic подключаются к телу запроса автоматически, но смысл остаётся тем же: недоверенные данные проходят через контракт до бизнес-логики. Разделяйте модели создания, ответа и обновления, если у них разные обязательные поля. Не храните секреты в repr и не отдавайте внутренний input без фильтра. Для больших проектов вынесите модели в отдельный модуль, но оставьте рядом примеры входа и тесты на границы.

Как изучить тему в Кодике

Начните со словарей, функций и исключений Python. Затем сравните ручные if с декларативной моделью. В Кодике сначала восстановите чистую логику без фреймворка, затем верните библиотеку и интерфейс Pydantic.

Сначала напишите одну ручную проверку, потом замените её Field и сравните сообщения. Финальная проверка для Pydantic: закрыть статью, объяснить путь данных и добавить одну функцию без копирования готового блока.

Что получится в итоге

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