Сериализация и десериализация: единые конвенции для Python и TypeScript

Представьте ситуацию: бэкенд на Python отправляет данные в фронтенд на TypeScript, и вдруг интерфейс ломается. Причина? Дата пришла в формате ISO-8601, а клиент ждал Unix timestamp. Или поле называется user_id на сервере, но userId в интерфейсе. Такие рассинхроны съедают часы разработки и отладки. Чтобы этого избежать, команды внедряют строгие правила сериализации данных.

Сериализация - это процесс преобразования объектов программы в формат для передачи или хранения (обычно JSON), а десериализация - обратное восстановление объекта из этого формата. Когда вы работаете с двумя языками, критически важно, чтобы обе стороны понимали «язык» данных одинаково. Это не просто вопрос синтаксиса, а вопрос архитектуры взаимодействия систем.

Почему стандартный JSON не решает всех проблем

JSON - универсальный формат обмена данными, но он беден типами. В отличие от TypeScript, где есть строгая типизация, JSON содержит только строки, числа, булевы значения, массивы, объекты и null. Это создает вакуум, который разработчики заполняют своими конвенциями. Если эти конвенции не задокументированы и не автоматизированы, они расходятся.

Основные точки конфликта обычно касаются трех аспектов:

• Именование полей: snake_case против camelCase.
• Типы данных: как передавать даты, деньги, ID.
• Структура ответа: как обернуть данные при успехе и ошибке.

Конвенция именования: выбор между snake_case и camelCase

В Python стандартом де-факто является snake_case (например, created_at). В экосистеме JavaScript и TypeScript доминирует camelCase (createdAt). Вы можете выбрать один стиль для всего API, но чаще всего приходится конвертировать данные на границе.

Ручная конвертация через маппинг ключей во всех запросах - плохая идея. Лучше использовать библиотеки, которые делают это автоматически. Например, в Python популярны pydantic или mashumaro, которые позволяют задать alias для полей. В TypeScript для парсинга часто используют zod или io-ts.

Даты и время: самый частый источник багов

Как передать дату? Вариант 1: Unix timestamp (число секунд с 1970 года). Вариант 2: Строка ISO-8601 ("2024-05-20T14:30:00Z"). Для взаимодействия Python и TypeScript лучше всего подходит ISO-8601 со указанием часового пояса (суффикс Z для UTC).

В Python объект datetime по умолчанию не сериализуется в JSON без специального обработчика. Библиотека pydantic автоматически превращает datetime в ISO-строку. На стороне TypeScript, если вы используете Date объект, браузер или Node.js корректно распарсят ISO-строку. Главное правило: всегда храните и передавайте время в UTC, а перевод в локальный часовой пояс пользователя делайте только на клиенте.

Числа и деньги: потеря точности

JavaScript имеет лишь один тип чисел - number (double precision floating point). Это значит, что большие целые числа (больше 2^53) могут терять точность. Если ваши ID пользователей или транзакций становятся слишком большими, используйте строки для передачи ID в JSON. Да, это выглядит странно ("id": "12345678901234567890"), но это гарантирует целостность данных.

Для денег никогда не используйте float. Передавайте суммы в минорных единицах (копейках, центах) как целые числа или строки. Например, вместо 10.50 передавайте 1050. Это исключает ошибки округления при вычислениях на любом языке.

Структура ответов API: единообразие

Когда все идет хорошо, ответ может быть просто объектом с данными. Но что делать при ошибках? Если Python возвращает {"error": "msg"}, а TypeScript ожидает {"message": "msg"}, хук обработки ошибок сломается. Зафиксируйте структуру обертки (wrapper).

Рекомендуемая структура успеха: { "data": { ... } } Рекомендуемая структура ошибки: { "error": { "code": "VALIDATION_ERROR", "message": "Field is required", "details": [...] } } Такой подход позволяет клиенту всегда проверять наличие поля data или error, не гадая, какой статус HTTP был возвращен (хотя статусы тоже важны).

Автоматизация через OpenAPI и генерацию кода

Лучший способ согласовать конвенции - убрать человеческий фактор. Используйте спецификацию OpenAPI (Swagger). Опишите ваш API в YAML или JSON файле. Затем сгенерируйте типы для TypeScript и модели для Python из этой спецификации.

Если вы меняете имя поля в спецификации, инструменты генерации обновят код на обеих сторонах. Это создает единый источник правды. Инструменты вроде prisma или orval для TypeScript и datamodel-code-generator для Python отлично справляются с этой задачей. Это не панацея, но снижает количество рассинхронов на 90%.

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

Если вы начинаете новый проект или рефакторите старый, вот чек-лист действий:

1. Зафиксируйте гайдлайн: Напишите документ, где указано, как называются поля, как передаются даты и деньги.
2. Выберите стек валидации: Pydantic для Python, Zod для TypeScript. Они оба поддерживают алиасы и трансформации.
3. Внедрите линтеры: ESLint для TS и Flake8/Ruff для Python помогут держать стиль кода, но главное - линтеры для API контрактов.
4. Тестируйте границы: Напишите интеграционные тесты, которые проверяют, что Python может распарсить то, что отправил TypeScript, и наоборот.

Согласованность в сериализации - это не бюрократия. Это способ сэкономить нервы всей команды. Когда данные предсказуемы, разработка фич ускоряется, а отладка становится проще. Начните с малого: выберите формат дат и стиль именования, и придерживайтесь их везде.