В чём разница между BaseModel и dataclasses в Pydantic?

BaseModel и dataclasses в Pydantic

Pydantic предоставляет два способа описать валидируемую структуру данных: унаследоваться от BaseModel или применить декоратор pydantic.dataclasses.dataclass к обычному классу. Оба подхода выполняют runtime-валидацию, но отличаются контрактом, возможностями и совместимостью.

BaseModel

BaseModel — родной инструмент Pydantic. Класс получает полный набор методов: model_validate(), model_dump(), model_dump_json(), model_json_schema(), model_copy() и другие. Поля описываются аннотациями типов и необязательным Field().

from pydantic import BaseModel, Field, ValidationError

class User(BaseModel):
    id: int
    name: str = Field(min_length=1, max_length=100)
    email: str
    age: int = Field(ge=0, le=150)

# Успешная валидация с автоприведением типов
user = User(id="42", name="Alice", email="alice@example.com", age=30)
print(user.id)          # 42 (int, строка приведена)
print(user.model_dump()) # {'id': 42, 'name': 'Alice', 'email': 'alice@example.com', 'age': 30}
print(user.model_dump_json())  # JSON-строка

# Ошибка валидации
try:
    User(id=1, name="", email="bad", age=-1)
except ValidationError as e:
    print(e.error_count())  # 2
    print(e.errors())       # список ошибок с path и msg

pydantic.dataclasses.dataclass

Декоратор @dataclass из модуля pydantic.dataclasses оборачивает стандартный Python-датакласс и добавляет валидацию при инициализации. Класс при этом остаётся совместимым с dataclasses.fields(), dataclasses.asdict() и другими утилитами стандартной библиотеки.

from pydantic.dataclasses import dataclass
from pydantic import Field, ValidationError
import dataclasses

@dataclass
class Point:
    x: float
    y: float
    label: str = Field(default="point", min_length=1)

# Создание с валидацией
p = Point(x="1.5", y=2, label="A")
print(p.x)   # 1.5 (float)
print(dataclasses.asdict(p))  # {'x': 1.5, 'y': 2.0, 'label': 'A'}

# Ошибка валидации
try:
    Point(x="bad", y=0)
except ValidationError as e:
    print(e)

Ключевые различия

• Сериализация: BaseModel имеет встроенные model_dump() и model_dump_json(). У pydantic-датакласса нет этих методов — для сериализации нужен dataclasses.asdict() или оборачивание в TypeAdapter.
• JSON Schema: BaseModel.model_json_schema() доступен напрямую. Для датакласса используют TypeAdapter(Point).json_schema().
• Мутабельность: BaseModel по умолчанию иммутабелен (атрибуты защищены), но можно включить model_config = ConfigDict(frozen=True) или наоборот разрешить присвоение. Датакласс мутабелен по умолчанию, frozen=True задаётся в декораторе.
• Наследование: BaseModel поддерживает полноценное наследование с переопределением полей и валидаторов. Наследование pydantic-датаклассов работает, но с ограничениями стандартного датакласса (порядок полей с дефолтами).
• Совместимость: Pydantic-датаклассы совместимы с библиотеками, ожидающими стандартные датаклассы (например, некоторые ORM-адаптеры, cattrs). BaseModel не является датаклассом.

Когда что выбирать

• Используйте BaseModel для request/response схем FastAPI, конфигурационных объектов, DTO — везде, где нужна полная мощь Pydantic.
• Используйте @dataclass из Pydantic, когда код должен оставаться совместимым со стандартными датаклассами, или вы постепенно добавляете валидацию в существующую кодовую базу.

from pydantic import BaseModel, TypeAdapter
from pydantic.dataclasses import dataclass as pydantic_dataclass
import dataclasses

# BaseModel — полный набор Pydantic
class Config(BaseModel):
    host: str = "localhost"
    port: int = 5432

cfg = Config(port="5432")
print(cfg.model_dump())        # {'host': 'localhost', 'port': 5432}
print(cfg.model_json_schema()) # JSON Schema dict

# pydantic dataclass — совместимость со стандартной библиотекой
@pydantic_dataclass
class Config2:
    host: str = "localhost"
    port: int = 5432

cfg2 = Config2(port="5432")
print(dataclasses.asdict(cfg2))  # {'host': 'localhost', 'port': 5432}

# JSON Schema через TypeAdapter
ta = TypeAdapter(Config2)
print(ta.json_schema())

Подводные камни

• Отсутствие model_dump у датакласса: попытка вызвать .model_dump() на pydantic-датаклассе приведёт к AttributeError. Используйте dataclasses.asdict() или TypeAdapter.
• Порядок полей при наследовании датакласса: стандартное ограничение Python — поле без дефолта не может следовать за полем с дефолтом. При наследовании это ограничение сохраняется, что может вызвать TypeError при объявлении класса.
• Мутация после создания: BaseModel по умолчанию запрещает присвоение атрибутов (model_config = ConfigDict(frozen=False) нужно явно включить). Если вы ожидаете мутабельный объект, явно настройте конфиг.
• Validators и dataclass: декораторы @field_validator и @model_validator работают в pydantic-датаклассах, но ошибки валидации возникают только при инициализации — прямое присвоение атрибута после создания валидацию не запускает.
• FastAPI и датаклассы: FastAPI принимает pydantic-датаклассы как тип параметра, но генерация OpenAPI-схемы может вести себя иначе, чем с BaseModel. Для response_model лучше использовать BaseModel.
• Смешивание стандартного и pydantic dataclass: если вы унаследуетесь от стандартного @dataclasses.dataclass и попытаетесь применить pydantic-декоратор, поведение будет непредсказуемым — всегда начинайте иерархию с одного типа.
• model_rebuild(): при forward references или сложных generic-моделях BaseModel требует явного вызова model_rebuild(). Для pydantic-датаклассов эта же проблема решается через rebuild_dataclass().
• Производительность: pydantic v2 (Rust-core) быстр в обоих случаях, но BaseModel имеет чуть меньше накладных расходов на сериализацию за счёт встроенных оптимизированных методов.

• Описывать basemodel vs dataclasses только как термин и не показывать механизм на минимальном примере.
• Игнорировать ошибки, пустые данные, конкурентный доступ или границы транзакции.
• Не связывать поведение с официальным контрактом Pydantic и реальной эксплуатацией.

• Объясняет basemodel vs dataclasses через последовательность действий, а не через набор ключевых слов.
• Приводит короткий кодовый пример или production-сценарий с ожидаемым поведением.
• Называет хотя бы один риск: производительность, безопасность, транзакции, память или сопровождение.