Автоматизация API-ручек и типов: как не ломать фронтенд после изменения backend

Одна из самых неприятных frontend-проблем — backend изменил поле, документация не обновилась, типы устарели, и ошибка всплыла только на стенде. Чем больше команда и API, тем чаще это происходит. Ручная синхронизация схем быстро перестаёт работать.

Решение — сделать контракт API машинно-проверяемым. Не полагаться на договорённости в чате, а генерировать типы, проверять совместимость и ловить breaking changes до deploy.

Контракт как источник правды

Для REST чаще всего используют OpenAPI. Для GraphQL роль контракта выполняет schema. Главное — выбрать один источник правды:

• backend генерирует schema из кода;
• schema пишется вручную и backend ей следует;
• контракт хранится отдельно и проверяется тестами.

Плохой вариант — когда документация живёт сама по себе, backend сам по себе, а frontend вручную копирует типы.

Codegen для frontend

Из OpenAPI можно генерировать:

• TypeScript types;
• API client;
• validators;
• mock handlers;
• документацию.

Это снижает количество ручного кода. Если backend поменял user_name на username, frontend узнает об этом на этапе компиляции, а не после жалобы QA.

Contract tests

Генерация типов не решает всё. Нужно проверять, что реальный backend отвечает по контракту. Contract tests могут:

• вызвать endpoint;
• проверить status codes;
• сравнить response schema;
• проверить обязательные поля;
• поймать несовместимые изменения.

Такие тесты особенно полезны в CI перед merge.

Breaking changes

Не каждое изменение одинаково опасно. Добавить необязательное поле обычно безопасно. Удалить поле, изменить тип или сделать optional поле обязательным — breaking change.

CI может сравнивать текущую schema с предыдущей и запрещать опасные изменения без версии API или согласования.

Версионирование

Если API используют несколько клиентов, нужна стратегия версий:

• /v1, /v2;
• header-based versioning;
• feature flags;
• backward-compatible changes;
• deprecation window.

Версионирование не должно быть формальностью. У старой версии должен быть срок жизни и план удаления.

Ошибки тоже часть контракта

Команды часто типизируют только успешный response. Но frontend также зависит от ошибок:

• формат validation errors;
• codes;
• messages;
• retryable/non-retryable;
• auth errors;
• rate limit response.

Если ошибки не описаны, UI начинает парсить текстовые сообщения и ломается при каждом изменении.

Итог

Автоматизация API-ручек и типов — это не «удобство для фронта», а защита delivery-процесса. OpenAPI, codegen, contract tests и CI-проверки превращают договорённости между backend и frontend в проверяемый контракт.

Чем раньше команда внедряет такую связку, тем меньше времени уходит на баги из серии «поле переименовали, но никто не заметил».