Full stack Developer

– apps/ – запускаемые приложения (frontend и каждый бэкенд).

– packages/ – общие библиотеки/артефакты, которые переиспользуются несколькими приложениями (в нашем случае – контракт и генерация типов/клиентов).

Почему инфраструктура вынесена в infra/, а не разбросана по приложениям?

Потому что инфраструктура у нас общая. Postgres/Redis/очередь – не «часть конкретного api-ts», они нужны всем реализациям.

Если размазать infra по приложениям:

– придётся дублировать docker-compose и конфиги;

– версии сервисов начнут расходиться;

– станет сложнее запускать и поддерживать окружение.

Папка infra/ делает инфраструктуру одной, а значит – повторяемой и предсказуемой.

Контракт как основа: OpenAPI-first

В этой книге мы идём подходом OpenAPI-first: сначала описываем API как контракт, а потом реализуем его на разных языках.

Это дисциплина, которая сначала кажется «лишней бюрократией», но очень быстро окупается:

– фронтенд получает типы и клиент без ручной работы;

– e2e‑тесты знают, что проверять, и могут дополнительно сверять схему;

– разные бэкенды реализуют один и тот же договор, без «творчества»;

– изменения API становятся управляемыми: видно, что сломается.

Наша цель в этой главе простая:

написать openapi.yaml, научиться генерировать из него типы/клиенты и заставить CI проверять, что контракт валиден.

Где живёт OpenAPI в нашем монорепо

Мы договорились: контракт лежит в одном месте.

Структура пакета:

text

/packages/shared-contract

openapi.yaml

/generated

/scripts

– openapi.yaml – главный файл спецификации.

– generated/ – сюда можно складывать сгенерированные артефакты (типы, клиенты).

– scripts/ – скрипты генерации и проверки.

Папки generated и scripts – опциональны, но они помогают держать порядок: «ручной код» отдельно, «генерация» отдельно.

Пишем первый openapi.yaml

Начнём с минимального, но реального API. Нам нужно что-то, что:

1) легко проверить e2e‑тестами;

2) пригодится для health-check;

3) задаст стиль ответов и ошибок.

Сделаем два эндпоинта:

– GET /health – проверка, что сервис жив.

– GET /api/version – показывает версию API (или приложения), чтобы удобно сравнивать окружения.

Создаём файл:

/packages/shared-contract/openapi.yaml

yaml

openapi: 3.0.3

info:

title: Demo API

version: 0.1.0

description: |

Контракт API для учебного проекта.

Все реализации (TS/Python/Java/Go) обязаны ему соответствовать.

servers:

– url: http://localhost:3001

description: Local dev (пример)

tags:

– name: system

description: Системные эндпоинты

paths:

/health:

get:

tags: [system]

summary: Health check

description: Проверяет, что сервис доступен

responses:

"200":

description: OK

content:

application/json:

schema:

$ref: "/components/schemas/HealthResponse"

/api/version:

get:

tags: [system]

summary: API version

description: Возвращает версию приложения/контракта

responses:

"200":

description: OK

content:

application/json:

schema:

$ref: "/components/schemas/VersionResponse"

components:

schemas:

HealthResponse:

type: object

additionalProperties: false

required: [status]

properties:

status:

type: string

enum: [ok]

VersionResponse:

type: object

additionalProperties: false

required: [version]

properties:

version:

type: string

example: "0.1.0"

Почему мы сразу добавили additionalProperties: false

Это важная деталь. Она означает: в ответах не должно быть неожиданных полей.

Если это не включать, сервер может вернуть лишнее, фронт случайно начнёт это использовать, а потом вы захотите убрать поле – и получите «тихий» breaking change.

С additionalProperties: false API становится строже, зато стабильнее.

Договоримся о стиле ошибок (на будущее)

Пока в контракте нет ошибок, но уже сейчас полезно задать единый формат. Тогда все реализации будут возвращать одно и то же.

Добавим схему ошибки в components/schemas (даже если эндпоинты пока её не используют):

yaml

components:

schemas:

ApiError:

type: object

additionalProperties: false

required: [code, message]

properties:

code:

type: string

example: "VALIDATION_ERROR"

message:

type: string

example: "Invalid request"

details:

type: object

additionalProperties: true

description: Дополнительная информация (опционально)

Позже мы начнём ссылаться на ApiError в ответах 400/401/404/500. Сейчас важно: мы заранее закрепили формат.

Генерируем клиентов и типы

OpenAPI полезен сам по себе как документация. Но настоящая сила – в генерации.

Что мы обычно хотим генерировать:

– TypeScript типы для фронтенда и e2e‑тестов;

– TypeScript API клиент (чтобы не писать fetch вручную);

– опционально: клиенты для других языков (если нужно).

Какие инструменты можно использовать

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

– OpenAPI Generator – умеет генерировать почти всё, поддерживает массу языков.

– Swagger Codegen – старый, но встречается.

– Для TS:

– генерация типов отдельно (например, из схем),

– генерация клиента (fetch/axios).

Практический совет: для старта проще всего выбрать один генератор, который делает TS‑клиент и типы, и пользоваться им везде.

Куда складывать результат

Есть два подхода:

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‑тесты – и убедиться, что он работает одинаково для любого языка.

Глава 1. TypeScript/Node – плюсы/минусы (практически)

TypeScript/Node.js – один из самых популярных вариантов для прикладных API: от небольших сервисов до больших BFF и API‑шлюзов. Его часто выбирают не потому, что он «самый быстрый» или «самый строгий», а потому что он быстро даёт результат и хорошо ложится на продуктовую разработку.

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

1.1. Что мы подразумеваем под TypeScript/Node.js в книге

Чтобы говорить предметно, зафиксируем контекст. Когда дальше в книге будет «TS/Node.js реализация», мы обычно имеем в виду:

– Node.js как runtime (чаще LTS‑версия).

– TypeScript как язык разработки.

– Веб‑фреймворк уровня Express/Fastify/Nest (выбор влияет на стиль, но не отменяет общие свойства платформы).

– Обязательное наличие:

– линтера (ESLint),

– форматтера (Prettier),

– тестов,

– сборки (tsc, иногда bundler),

– строгих настроек TypeScript (насколько возможно).

Что полезно установить для работы

Ниже – типичный минимум. Конкретные версии не важны, важна идея:

– Node.js (LTS) – среда выполнения.

– npm / pnpm / yarn – менеджер пакетов (любое одно).

– TypeScript – компилятор и типизация.

– Docker – удобно для инфраструктуры (PostgreSQL/Redis/очереди), чтобы окружение было одинаковым у всех.

– HTTP‑клиент для ручной проверки: curl или Postman/Insomnia.

– Инструмент для профилирования (на будущее): встроенный Node inspector и/или клинические утилиты типа autocannon для нагрузочного прогона.

Это не «обязательный список для счастья», но с ним меньше сюрпризов.

1.2. Плюсы: почему TS/Node.js часто выигрывает в реальности

Плюс 1. Максимальная скорость разработки и огромная экосистема

На практике Node.js выигрывает там, где важны:

– быстро поднять сервис;

– быстро интегрироваться со сторонними системами;

– быстро менять продуктовую логику.

Причина проста: экосистема.

Для большинства задач уже есть готовые решения:

– авторизация (JWT, OAuth),

– валидация входных данных,

– логирование, трассировка,

– очереди, кэш, базы данных,

– платежи, интеграции, SDK внешних сервисов,

– генерация клиента из OpenAPI.

Это снижает «время до первой работающей версии» и уменьшает риск, что вам придётся писать инфраструктурные куски самим.

Что вы ощущаете в проекте:

– меньше времени уходит на «поднять каркас»;

– много вещей можно сделать через конфигурацию;

– проще нанять разработчиков: Node/TS распространены.

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

Плюс 2. Один язык на фронт и бэк – удобно для full‑stack

Когда фронтенд и бэкенд на одном языке, появляется набор «мелких», но очень ощутимых преимуществ:

– общие принципы типизации и структуры данных;

– один стиль работы с JSON и датами;

– проще «перекидывать» людей между задачами;

– проще писать BFF (Backend For Frontend), где API подстраивается под UI.

Если команда в основном из фронтендеров, TypeScript‑бэкенд – это самый короткий путь:

– не нужно учить Java/Go «с нуля»,

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

Особенно хорошо этот плюс раскрывается, когда у вас:

– много экранов и фич,

– API постоянно меняется,

– продукт ещё ищет «правильную форму».

Плюс 3. TypeScript даёт контракты, автокомплит и рефакторинг

TypeScript – это не «магическая защита от багов», но это мощный инструмент, который:

– делает структуры данных явными;

– помогает IDE подсказывать правильные поля и типы;

– позволяет рефакторить безопаснее (переименования, перемещения, выделения типов).

На практике вы быстро замечаете две вещи:

1) Код становится самодокументируемым.

Хорошо описанные типы входа/выхода читаются как документация.

2) Меньше «неожиданных» ошибок на ровном месте.

Например, когда поле называется `createdAt`, а вы случайно использовали `createAt`.

Но есть тонкость: типы в TS особенно хороши, когда вы:

– избегаете `any`,

– ограничиваете «непроверенные» данные на границе (HTTP запросы, внешние API),

– используете строгие настройки компилятора.

Иначе TypeScript может превратиться в видимость безопасности.

Плюс 4. Отлично для BFF, API‑шлюзов и SaaS

Есть классы задач, где Node.js чувствует себя «дома»:

– BFF: собрать данные из нескольких источников, подготовить JSON под конкретный UI.

– API‑шлюз: проксирование, авторизация, rate limit, агрегация.

– SaaS‑продукты: много бизнес‑логики, много интеграций, постоянные изменения.

Node.js особенно силён в I/O‑нагрузке:

– много запросов,

– много походов в базу/кэш/внешние сервисы,

– много «склеивания» ответов.

Здесь важнее не «сырой CPU», а скорость разработки и удобство интеграций.

1.3. Минусы: где Node.js может ударить больно

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

Минус 1. Производительность и предсказуемость latency обычно хуже, чем у Go/Java

В среднем, при равной реализации и при нагрузке, Go и Java часто дают:

– более высокую пропускную способность,

– более стабильные хвостовые задержки (p95/p99),

– лучшее использование CPU.

Node.js может показывать отличные результаты, но есть типичные причины, почему latency «плывёт»:

– один event loop: если вы случайно сделали тяжёлую синхронную работу, она блокирует обработку запросов;

– сборка мусора (GC): паузы могут проявляться как редкие, но неприятные пики;

– зависимости: одна «неудачная» библиотека может создать нагрузку и ухудшить хвосты.

Что это значит практично:

– для большинства продуктовых API это не проблема на старте;

– но при росте нагрузки и требований к p99 придётся:

– профилировать,

– контролировать память,

– оптимизировать горячие места,

– иногда выносить CPU‑тяжёлое в отдельные воркеры/сервисы.

Если у вас система, где критичны микросекунды/миллисекунды и стабильность p99 (например, высокочастотный трейдинг), Node.js будет сложнее «довести» до уровня Go/Java.

Минус 2. “Железобетонная” типобезопасность сложнее, чем в Java

TypeScript – язык со статической типизацией, но он остаётся «надстройкой» над JavaScript. Это проявляется в трёх местах:

1) Границы системы

Всё, что пришло извне (HTTP запрос, сообщение из очереди, ответ другого сервиса), по-настоящему имеет тип `unknown`.

Если вы не валидируете входные данные, типы становятся самообманом.

2) Лазейки типизации

`any`, нестрогие настройки компилятора, приведения типов ради скорости – и вот типы уже не защищают.

3) Сложные типы могут стать “типовой магией”

TypeScript позволяет строить очень мощные типовые конструкции, но иногда это превращает код в ребус:

– сложно читать,

– сложно дебажить,

– сложно объяснять новичкам.

Практический вывод: в TS безопасность типов достигается не «по умолчанию», а дисциплиной:

– строгий `tsconfig`,

– минимум `any`,

– валидация входов (схемы),

– генерация типов из контракта (OpenAPI) вместо ручного описания.

Минус 3. Память и GC под нагрузкой требуют аккуратности

В Node.js легко не заметить, как сервис начинает потреблять слишком много памяти:

– большие JSON‑ответы;

– лишние копии объектов;

– хранение данных в кэше процесса без ограничений;

– утечки через глобальные структуры;

– слишком «жирные» зависимости.

А потом наступает момент, когда:

– контейнер перезапускается по OOM,

– GC начинает чаще работать,

– latency становится зубчатым.

Практически это решается, но нужно:

– следить за memory usage,

– уметь делать heap snapshot,

– ограничивать кэши и буферы,

– понимать жизненный цикл объектов.

Это не означает, что Node «плохой». Это означает, что под нагрузкой вам понадобится инженерная внимательность.

Минус 4. Нужна дисциплина архитектуры – иначе проект “расползётся”

Node.js и TypeScript дают большую свободу. Это хорошо, пока проект маленький. Но свобода быстро превращается в хаос, если нет правил:

– где лежит бизнес‑логика,

– где слой доступа к данным,

– как устроены модули,

– как организованы DTO/схемы,

– как оформляются ошибки,

– как пишутся тесты.

Симптомы «расползания» обычно такие:

– контроллеры по 300 строк;

– бизнес‑логика размазана по роутам;

– разные форматы ошибок в разных местах;

– отсутствие границ между слоями;

– типы начинают дублироваться и расходиться.

Это решается не «правильным фреймворком», а правилами и привычками:

– единый стиль проекта,

– единые контракты,

– генерация из OpenAPI,

– архитектурные границы.

Если дисциплины нет, TS/Node проект может деградировать быстрее, чем аналогичный на более «тяжёлых» платформах, где часть структуры навязывается инструментами.

1.4. Когда выбирать TypeScript/Node.js

Ниже – ситуации, когда выбор TS/Node обычно оправдан и даёт максимальную отдачу.

Сценарий 1. Быстрое MVP → продукт → масштабирование с профилированием

Самый типичный путь:

1) Вы делаете MVP быстро: больше ценности, меньше церемоний.

2) Продукт начинает расти: добавляются фичи, интеграции, команды.

3) Появляется нагрузка: вы профилируете, оптимизируете, усиливаете наблюдаемость.

4) Если нужно, выносите горячие места:

– в отдельные воркеры,

– в отдельные сервисы (на Go/Java, если действительно требуется).

Node.js отлично подходит как «двигатель продукта», где скорость изменений важнее абсолютной эффективности.

Сценарий 2. Команда фронтендеров, которым нужен бэк

Если у вас сильная фронтенд‑команда и нужно быстро закрыть бэкенд‑потребности:

– TypeScript снижает порог входа;

– общие подходы к типам и контрактам упрощают коммуникацию;

– проще поддерживать BFF и API под нужды UI.

Обычно в таких командах успех зависит от двух вещей:

– контракт (OpenAPI-first, как мы договорились);

– архитектурные правила (иначе всё уйдёт в «быстрее бы работало»).

Сценарий 3. BFF/API‑шлюз как отдельный слой

Если ваш бэкенд – это в основном:

– агрегация,

– маршрутизация,

– преобразование данных,

– авторизация и ограничения,

то Node.js – сильный кандидат, потому что:

– I/O‑операции – его естественная среда,

– экосистема даёт массу готовых компонентов,

– разработка и поддержка быстрее.

1.5. Практические рекомендации, чтобы плюсы не превратились в минусы

Эта часть короткая, но очень прикладная: что стоит сделать почти в любом TS/Node API проекте, чтобы жить спокойнее.

1) Делайте строгий TypeScript “по умолчанию”

Смысл: пусть компилятор «ворчит», пока проект маленький. Это дешевле, чем переписывать позже.

– включайте строгие проверки (`strict` и связанные флаги);

– минимизируйте `any`;

– работайте с внешними данными как с `unknown` и валидируйте их.

2) Валидируйте входы и выходы на границе

Типы внутри кода – хорошо. Но запрос из интернета не становится типом автоматически.

– входные данные: валидируем (схемы/валидаторы);

– выходные данные: следим, чтобы соответствовали контракту.

Это особенно важно, если вы хотите, чтобы разные реализации (TS/Python/Go/Java) вели себя одинаково.

3) Следите за размером зависимостей и качеством пакетов

Экосистема огромная, но это не значит, что любую библиотеку стоит тянуть в проект.

Полезные привычки:

– не добавлять зависимость «ради одной функции»;

– смотреть на поддержку и актуальность;

– обновлять регулярно, а не раз в год «одним большим взрывом».

4) Добавьте наблюдаемость до того, как станет больно

Минимум, который окупается рано:

– структурированные логи,

– корреляционный id,

– метрики (хотя бы время ответа и ошибки),

– трассировка (по возможности).

Так вы быстрее поймёте, где Node «упёрся» – в базу, в внешние API или в CPU.

5) Держите архитектуру простой, но с границами

Не обязательно усложнять. Но границы должны быть:

– transport слой (HTTP) отдельно,

– бизнес‑логика отдельно,

– доступ к данным отдельно,

– общие типы/контракт отдельно.

Это снижает «расползание» и облегчает тестирование.

1.6. Итог

TypeScript/Node.js – выбор про скорость и удобство:

– быстро разрабатывать,

– легко интегрироваться,

– удобно жить в одном языке с фронтендом,

– отлично подходит для BFF и продуктовых API.

Но за это платите необходимостью инженерной дисциплины:

– следить за типовой безопасностью на границах,

– контролировать память и GC под нагрузкой,

– профилировать и работать с latency,

– не давать архитектуре расползаться.

Если вы хотите быстро выйти на рынок, постоянно менять продукт и у вас сильная фронтенд‑команда – TS/Node почти всегда хороший старт. А дальше вы либо продолжите масштабироваться на Node с профилированием, либо точечно вынесете критичные части туда, где лучше предсказуемость и производительность.

Глава 2. Python – плюсы/минусы

Python часто выбирают не из‑за «идеальной архитектуры» «самой высокой производ», а из‑за очень практичной вещи: на нём быстрее всего превращать идею в работающий код. Это язык, на котором одинаково комфортно написать API, скрипт мигра данных, интеграцию со сторонним сервисом, джобу для очереди и небольшой ML‑пайплайн.

Но у скорости есть цена: слабее статическая типизация, выше риск ошибок времени выполнения, а под серьёзной нагрузкой или при сложном параллелизме придётся думать больше, чем хотелось бы.

В этой главе разберём Python «по‑земному»: где он особенно хорош, где может подставить и как понять, подходит ли он под ваш сервис.

2.1. Что мы подразумеваем под Python‑бэкендом

Под «Python‑бэкендом» в этой книге обычно подразумевается:

– Python 3.x (желательно актуальный, не «как на сервере поставили 5 лет назад»).

– Web API на одном из фреймворков:

– FastAPI (часто лучший баланс для современных API),

– Django (если нужен «комбайн» с ORM, админкой и большим количеством встроенных решений),

– Flask (минималистичный вариант).

– Работа в контейнерах (часто Docker), чтобы окружение было повторяемым.

– Тесты и линтинг как обязательная часть проекта.

Что стоит установить для работы

Минимальный набор, который обычно облегчает жизнь:

– Python 3 (лучше ставить через менеджер версий вроде `pyenv`, если вы на macOS/Linux).

– pip (идёт вместе с Python) + менеджер зависимостей:

– `poetry` или `uv` (быстро и удобно),

– либо классический `pip` + `requirements.txt` (простая модель, но требует дисциплины).

– Docker (PostgreSQL/Redis/очереди удобно поднимать контейнерами).

– Postman/Insomnia или просто `curl` для ручной проверки API.

– Инструменты качества кода:

– форматирование: `ruff format` или `black`,

– линтинг: `ruff`,

– типизация: `mypy` или `pyright`,