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 с профилированием, либо точечно вынесете критичные части туда, где лучше предсказуемость и производительность.