Валидация данных в Python и TypeScript: как согласовать проверки

Представьте ситуацию: фронтенд отправляет объект с полем email, где стоит пустая строка. Бэкенд на Python молча принимает это, а через час база данных падает из-за нарушения уникальности или бизнес-логика ломается. Знакомо? Проблема не в том, что кто-то ошибся. Проблема в том, что правила валидации живут в двух разных мирах: один на клиенте, другой на сервере, и они часто расходятся.

Согласованная валидация данных - это подход, при котором правила проверки входных параметров одинаковы для клиентского приложения (TypeScript) и серверной части (Python). Это снижает количество багов, ускоряет отладку и делает API более предсказуемым для разработчиков.

Почему важно синхронизировать проверки

Многие команды думают так: «На фронте мы проверяем для UX, а на бэке - для безопасности». Логично звучит, но на практике это приводит к дублированию кода и рассинхрону. Если вы меняете формат даты в модели, вам нужно обновить код в двух местах. Забыли про одно место - получили ошибку в продакшене.

Ключевая цель здесь - единый источник истины (Single Source of Truth). Когда правила валидации определены в одном месте и автоматически применяются на обоих концах стека, вы получаете:

• Меньше ручного тестирования граничных случаев.
• Быстрый онбординг новых разработчиков: им достаточно прочитать одну схему.
• Автоматическую генерацию документации API, которая всегда актуальна.

Инструменты: Pydantic и Zod

Для реализации этого подхода чаще всего используют Pydantic в Python и библиотеку для валидации объектов JavaScript/TypeScript. На стороне Python Pydantic позволяет описывать модели классовом, указывая типы полей и ограничения. Например, поле age должно быть целым числом больше нуля.

На стороне TypeScript популярным выбором является Zod - библиотека, которая позволяет описывать схемы данных с типами и проверками. Она интегрируется с TypeScript, обеспечивая строгую типизацию. Если данные не проходят проверку, Zod возвращает понятные ошибки, которые можно показать пользователю.

Как связать Python и TypeScript: JSON Schema

Золотой стандарт для обмена правилами валидации между языками - JSON Schema - спецификация для описания структуры JSON-объектов. Pydantic умеет автоматически генерировать JSON Schema из ваших моделей. Zod также может читать JSON Schema (через дополнительные пакеты или ручную конвертацию), хотя нативная поддержка немного сложнее, чем у Pydantic.

Рабочий процесс выглядит так:

1. Вы определяете модель данных в Python с помощью Pydantic.
2. Скрипт сборки проекта генерирует файл schema.json из этой модели.
3. На стороне TypeScript вы используете этот файл для создания схем Zod или напрямую для валидации.
4. Оба слоя теперь используют одни и те же правила: длины строк, форматы дат, допустимые значения.

Это устраняет проблему «магии», когда разработчик фронтера гадает, какие именно поля нужны на бэкенде. Он видит точную схему.

Практический пример: форма регистрации

Давайте посмотрим на конкретный кейс. У нас есть форма регистрации пользователя. Поля: username, email, password.

В Python (Pydantic):

from pydantic import BaseModel, EmailStr, Field

class UserCreate(BaseModel):
    username: str = Field(..., min_length=3, max_length=50)
    email: EmailStr
    password: str = Field(..., min_length=8)

Эта модель генерирует JSON Schema, где указано, что username - строка длиной от 3 до 50 символов, email должен соответствовать RFC 5322, а password - минимум 8 символов.

В TypeScript (Zod) мы можем вручную написать эквивалентную схему, опираясь на эту документацию, или использовать инструменты автоматической генерации. Результат будет таким:

import { z } from 'zod';

const UserCreateSchema = z.object({
  username: z.string().min(3).max(50),
  email: z.string().email(),
  password: z.string().min(8)
});

type UserCreate = z.infer<typeof UserCreateSchema>;

Теперь, если пользователь вводит слишком короткий логин, ошибка появится сразу на фронте. Но даже если он каким-то образом обойдет клиентскую проверку (например, через Postman), бэкенд на Python вернет тот же самый код ошибки с тем же сообщением. Согласованность достигнута.

Типовые ошибки и как их избежать

Даже при использовании этих инструментов разработчики часто совершают следующие ошибки:

• Разные версии библиотек. Если Pydantic обновился и изменил формат ошибок, а Zod остался на старой версии, сообщения могут не совпадать. Всегда фиксируйте версии зависимостей.
• Игнорирование сериализации. Pydantic преобразует объекты в dict, Zod работает с plain objects. Убедитесь, что даты и числа передаются в формате ISO 8601 и JSON-friendly форматах.
• Ручное дублирование логики. Не пишите отдельные функции для проверки пароля на бэке и фронте. Используйте общие схемы. Если бизнес-правило сложное (например, «пароль не должен содержать часть имени»), лучше вынести его в отдельную функцию, которую можно вызвать из обеих сторон, или четко задокументировать в схеме.

Альтернативы и новые подходы

Хотя связка Pydantic + Zod является стандартом де-факто, существуют и другие пути. Некоторые команды используют OpenAPI (Swagger) - спецификация для описания RESTful API. FastAPI автоматически генерирует OpenAPI документацию из Pydantic-моделей. Инструменты вроде openapi-typescript могут сгенерировать типы TypeScript прямо из этой спецификации. Это дает не только валидацию, но и типизацию HTTP-клиента.

Другой тренд - использование монолитных схемных редакторов, где вы пишете схему один раз (например, в YAML или JSON), и она компилируется в код для Python, TypeScript, Go и других языков. Это повышает порог входа, но гарантирует 100% синхронизацию.

Чек-лист для внедрения

Если вы хотите внедрить согласованную валидацию в свой проект, вот пошаговый план:

1. Выберите библиотеку для Python (рекомендуется Pydantic v2+).
2. Выберите библиотеку для TypeScript (Zod, Yup или Joi).
3. Создайте скрипт CI/CD, который генерирует JSON Schema из Python-кода при каждом коммите.
4. Добавьте этот файл в репозиторий фронтенда (или раздавайте его через endpoint).
5. Напишите юнит-тесты, которые проверяют, что схемы на бэке и фронте соответствуют друг другу (можно сравнить структуру JSON Schema).
6. Обучите команду: все новые поля должны добавляться сначала в модель Python, затем генерироваться для фронта.

Такой подход требует первоначальных затрат времени, но окупается сторицей при масштабировании команды и продукта. Вы перестаете тратить часы на поиск того, почему фронт отправил «неправильные» данные, а просто смотрите в единую схему.

Часто задаваемые вопросы