Юрий Белк – Full stack Developer (страница 6)

Обычно внутри:

– контроллеры/роуты;

– сервисы (бизнес-логика);

– слой доступа к данным;

– конфиг приложения и переменные окружения.

/apps/api-py

Бэкенд на Python (например, FastAPI). Хорош для скорости разработки, удобных деклараций схем и читабельного кода.

Обычно внутри:

– роуты (эндпоинты);

– pydantic‑модели (или аналоги);

– зависимости (DI), конфиги;

– миграции БД (если используем).

/apps/api-java

Бэкенд на JVM (чаще всего Spring Boot; в книге мы можем использовать Java или Kotlin). Это классический вариант для корпоративных систем.

Обычно внутри:

– контроллеры;

– сервисы и репозитории;

– конфигурация, профили окружений;

– сборка (Gradle/Maven).

/apps/api-go

Бэкенд на Go (например, chi или gin). Его сильные стороны – производительность, простота деплоя, предсказуемое потребление памяти.

Обычно внутри:

– роутер и хендлеры;

– слой бизнес-логики;

– слой хранения;

– конфиг и сборка в один бинарник.

Общее правило для apps/*

Каждое приложение в apps/ должно уметь:

1. Запускаться в dev‑режиме одной командой (например, dev).

2. Поднимать соединение с инфраструктурой из infra (Postgres/Redis).

3. Иметь health-check (например, GET /health).

4. Иметь настройку порта через переменные окружения.

Эти правила сильно упрощают e2e‑тесты и CI: тестам не важно, на чём написан API – важно, что он доступен и соответствует контракту.

packages/: общее и переиспользуемое

Если apps/ – это «то, что мы запускаем», то packages/ – это «то, что мы переиспользуем».

/packages/shared-contract

Это одна из ключевых папок в книге. Здесь живёт контракт между фронтом и бэкендом – OpenAPI‑описание, а также всё, что из него генерируется.

Типичное содержимое:

– openapi.yaml – главный файл контракта;

– папка со сгенерированными TypeScript‑типами;

– сгенерированный API‑клиент для фронтенда и тестов;

– скрипты для генерации (чтобы процесс был одинаковым у всех).

Почему это важно:

– контракт лежит в одном месте;

– фронтенд и тесты используют один и тот же источник;

– мы уменьшаем шанс «фронт ожидал одно, бэкенд вернул другое».

Правило: если меняется API, сначала меняем OpenAPI в shared-contract, потом обновляем реализации.

infra/: инфраструктура проекта

Папка infra/ – это всё, что не является кодом приложения, но нужно для работы системы.

Что здесь может быть

– docker-compose.yml для локальной инфраструктуры (Postgres, Redis, очереди);

– конфиги и скрипты инициализации;

– папки под Kubernetes‑манифесты (если дойдём до них);

– Terraform‑файлы (если будем описывать облачную инфраструктуру).

На старте нам чаще всего достаточно docker-compose, потому что это быстрый способ поднять окружение, одинаковое у всех.

Почему инфраструктура в отдельной папке?

Чтобы она была общей для всех бэкендов. Нам не нужно четыре отдельных compose‑файла – иначе мы будем править одно и то же в четырёх местах.

tests/e2e: одни тесты на все API

Папка /tests/e2e содержит end-to-end тесты, которые запускаются против любого из бэкендов. Это важный принцип книги: мы сравниваем реализации честно, по одинаковым проверкам.

Что делают e2e‑тесты:

– поднимают окружение (или подключаются к уже запущенному);

– делают реальные HTTP‑запросы к API;

– проверяют статус-коды, тело ответа, ошибки;

– (опционально) сверяют ответы со схемой OpenAPI.

Как это выглядит на практике: