Юрий Белк – Full stack Developer (страница 10)
1) Коммитить generated в репозиторий
Плюсы: быстро, всё видно, CI проще.
Минусы: лишние диффы, больше шума в PR.
2) Не коммитить, генерировать в CI и локально
Плюсы: чище репозиторий.
Минусы: нужно следить, чтобы все запускали генерацию.
Для учебного проекта допустимы оба. Важно не «что лучше в вакууме», а чтобы команда договорилась.
В нашей структуре логично держать генерацию здесь:
– packages/shared-contract/generated/
Как встроить генерацию в рабочий процесс
Нам нужно, чтобы генерация была:
– одинаковой у всех
– воспроизводимой
– не зависела от ручных действий
Минимальная схема работы:
1. Меняем openapi.yaml.
2. Запускаем генерацию (скрипт).
3. Фронтенд и тесты используют обновлённые типы/клиент.
Даже если вы пока не пишете реальные команды, полезно уже сейчас завести «точку входа», например:
– packages/shared-contract/scripts/generate
– packages/shared-contract/scripts/validate
Важно: не размазывать генерацию по разным местам. Контракт и его обслуживание должны жить рядом.
Валидация контракта в CI
Контракт имеет смысл только тогда, когда он валиден и изменения контролируются.
В CI нам нужны проверки:
1) OpenAPI файл корректный YAML
2) OpenAPI соответствует схеме OpenAPI 3.0.x
3) (опционально) в контракте нет грубых проблем (линтинг, стиль, ошибки описания)
Что именно проверять
Минимально достаточно:
– «файл парсится»
– «спецификация валидна»
Чуть лучше:
– запретить дубли, неиспользуемые схемы, неописанные ответы
– требовать operationId на каждом эндпоинте (удобно для генерации клиентов)
Например, можно договориться, что каждый endpoint обязан иметь operationId. Это выглядит так:
yaml
/health:
get:
operationId: getHealth
…
Почему это удобно:
– генератор делает стабильные имена методов;
– проще искать операции в коде и в логах.
Как CI будет это использовать
Идея простая:
– на каждый PR запускается job,
– job валидирует openapi.yaml,
– если файл сломан – PR не проходит.
Так вы избегаете ситуации «спецификация поехала, генерация упала у половины команды».
Правила изменения API (очень коротко)
Чтобы OpenAPI-first реально работал, вводим базовые правила:
1. Любое изменение API начинается с изменения openapi.yaml.
Не наоборот.
2. После изменения контракта должны обновиться генерации (типы/клиенты).
3. Реализации API обновляются после контракта и должны проходить e2e‑тесты.
Это создаёт правильную последовательность: контракт → инструменты → реализация → тесты.
Что будет в следующем разделе
Дальше мы сделаем первый минимальный API на одной из платформ (обычно удобно начать с TypeScript или Python, потому что быстрее старт), и:
– поднимем /health и /api/version так, чтобы они соответствовали OpenAPI;
– подключим e2e‑тесты из /tests/e2e, которые будут проверять эти два эндпоинта;
– подготовим основу, чтобы затем легко переключаться между api-ts, api-py, api-java, api-go.
Главная цель следующего шага: впервые увидеть замкнутый цикл
контракт → реализация → e2e‑тесты – и убедиться, что он работает одинаково для любого языка.