Full stack Developer

Юрий Белк

Full stack Developer

Об чём речь?

Книга‑туториал (максимально практическая): Full‑Stack + Backend Engineering на TS / Python / Java / Go

Сравнение языков, пошаговые проекты, одна предметная область, одинаковые требования.

Чтобы вы могли писать один и тот же продукт четырьмя реализациями бэкенда (TS/Python/Java/Go) и одной фронтенд‑частью, а затем сравнивать: скорость разработки, качество, тестируемость, производительность, сложность деплоя, типизацию, экосистему.

Как устроена книга

Главная идея

Мы строим один и тот же продукт (например, TaskFlow – сервис задач/проектов/команд):

Frontend: TypeScript + React/Next.js (единый для всех)

Backend: 4 реализации одного API:

1) Node.js + TypeScript (например, NestJS/Fastify)

2) Python (FastAPI)

3) Java (Spring Boot)

4) Go (Gin/Fiber/chi)

DB: PostgreSQL

Очереди: (опционально) RabbitMQ/NATS/Kafka (раздел сравнения)

Кэш: Redis

Observability: OpenTelemetry + Prometheus + Grafana + Loki

Infra: Docker Compose → CI/CD → Kubernetes (опционально)

На что будет опираться каждая реализация

Единая OpenAPI спецификация (контракт)

Единая схема БД и миграции

Единые acceptance tests (e2e) для всех реализаций

Единый набор сценариев нагрузки (k6/Locust/JMeter)

Для кого?

От “почти ноль” до уровня уверенного инженера

Для тех, кто хочет практику, но при этом понимать компромиссы

Стандартная структура каждой главы (шаблон)

Каждая глава оформляется одинаково:

1. Цель и результат (что получится в конце)

2. Предварительные требования

3. Шаги (команды + код)

4. Проверка результата (что увидеть/какие тесты проходят)

5. Типовые ошибки и дебаг

6. Домашка/усиление

7. Сравнение TS vs Python vs Java vs Go (если применимо)

Раздел I. Подготовка: инструменты, репо, “скелет книги”

Этот раздел нужен, чтобы один раз настроить окружение и дальше спокойно проходить всю книгу. Мы будем сравнивать несколько бэкендов (TypeScript, Python, JVM, Go) и один фронтенд, поэтому важно сразу договориться о правилах: как ставим зависимости, как запускаем сервисы, где живут контракты API, и как устроен репозиторий.

Главная идея: один монорепозиторий, один docker-compose для инфраструктуры, один контракт OpenAPI, и единые e2e‑тесты, которые одинаково проверяют любой бэкенд.

Глава 1. Как развернуть окружение

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

1.1. macOS / Linux / Windows (WSL2)

macOS

Обычно достаточно:

– терминал (встроенный или iTerm2),

– пакетный менеджер (например, Homebrew),

– Docker Desktop.

Linux

Удобнее всего, когда:

– есть нормальный bash/zsh,

– Docker установлен нативно,

– вы добавили пользователя в группу docker, чтобы не писать sudo на каждый запуск.

Windows

Рекомендуемый путь – WSL2:

– ставите WSL2,

– ставите Ubuntu,

– работаете внутри Linux‑окружения,

– Docker Desktop на Windows подключается к WSL2.

Так вы избегаете большинства проблем с путями, правами, файловой системой и скоростью работы инструментов.

1.2. Git, SSH, GPG (подпись коммитов)

Git

Проверьте:

bash

git –version

Настройте имя и почту (один раз):

bash

git config –global user.name "Your Name"

git config –global user.email "[e-mail]"

SSH (для доступа к удалённым репозиториям)

Создайте ключ:

bash

ssh-keygen -t ed25519 -C "[e-mail]"

Добавьте ключ в ssh-agent:

bash

eval "$(ssh-agent -s)"

ssh-add ~/.ssh/id_ed25519

Дальше публичный ключ (~/.ssh/id_ed25519.pub) добавляется в ваш Git‑хостинг.

GPG (подпись коммитов)

Подпись коммитов – это не “обязательная красота”, а способ снизить риск подмены авторства и упростить аудит изменений. Если у вас в команде принято подписывать коммиты – включайте сразу.

– Установите GPG (на macOS часто через brew, на Linux через пакетный менеджер).

– Сгенерируйте ключ:

bash

gpg –full-generate-key

– Узнайте ID ключа:

bash

gpg –list-secret-keys –keyid-format=long

– Включите подпись коммитов:

bash

git config –global commit.gpgsign true

git config –global user.signingkey

Если подпись не нужна – можно пропустить. На содержание книги это не влияет, но полезно как привычка.

1.3. Docker и Docker Compose

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

Проверьте:

bash

docker –version

docker compose version

Мы будем использовать команду нового формата:

bash

docker compose up -d

Важно: приложения (NestJS/FastAPI/Spring/Go) можно запускать и локально, и в контейнерах. В книге мы будем чаще запускать их локально, а инфраструктуру – в контейнерах. Это обычно быстрее для разработки.

1.4. Языки и менеджеры версий

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

Node.js: nvm

Для TypeScript и Next.js нам нужен Node.js и pnpm.

– Установите nvm.

– Поставьте нужную версию Node:

bash

nvm install 20

nvm use 20

– Включите pnpm (через corepack):

bash

corepack enable

corepack prepare pnpm@latest –activate

pnpm –version

Почему pnpm: он быстрее и экономнее по диску, особенно в монорепозитории.

Python: pyenv или uv

Есть два популярных пути:

Вариант А: pyenv – классический менеджер версий Python.

Вариант Б: uv – современный быстрый инструмент, который часто заменяет и pip, и venv.

Для книги подойдёт любой. Если хочется проще и быстрее по зависимостям – выбирайте uv.

Минимально важно: чтобы python и pip были предсказуемой версии, а зависимости проекта ставились в изолированное окружение.

Java/Kotlin: sdkman

Для Spring Boot (и Kotlin) удобно использовать sdkman:

– ставим sdkman,

– выбираем JDK (например, 21):

bash

sdk install java 21.0.2-tem

java -version

Go: asdf (или родной установщик)

Go можно ставить напрямую, но для управления версиями удобен asdf:

– ставим asdf,

– ставим Go нужной версии,

– проверяем:

bash

go version

Если asdf не хочется – поставьте Go из официального дистрибутива, это тоже нормально.

0.1.5. IDE и плагины

VS Code (как “универсальный редактор”)

VS Code удобен тем, что в одном окне можно держать весь монорепозиторий.

Рекомендуемые плагины:

– ESLint, Prettier (TS/JS)

– Prisma (подсветка схем)

– Python (официальный)

– Pylance

– Go (официальный)

– Java Extension Pack (если хотите работать с JVM в VS Code)

– OpenAPI (подсветка и валидация YAML)

– Docker

IntelliJ IDEA (для JVM)

Если вы всерьёз делаете Spring Boot/Kotlin – IntelliJ IDEA будет самым комфортным вариантом: автодополнение, дебаг, Gradle/Maven, рефакторинги.

GoLand (опционально)

Хорош для Go, но не обязателен: VS Code + Go plugin тоже отлично справляется.

0.1.6. Devcontainer: добавлять сразу?

Да, добавляем сразу, но как необязательный способ запуска.

Идея devcontainer:

– репозиторий содержит описание окружения,

– VS Code может открыть проект “в контейнере”,

– версии Node/Python/Go/Java будут одинаковыми у всех.

При этом:

– обычный запуск через терминал и docker-compose остаётся “по умолчанию”,

– devcontainer – это страховка и удобство.

В репозитории обычно появляются:

– .devcontainer/devcontainer.json

– Dockerfile для dev‑образа (если нужно)

– инструкции по установке расширений и запуску compose.

Монорепозиторий и структура

Мы используем монорепозиторий: один Git‑репо, внутри которого живут фронт, несколько бэкендов, общие пакеты и инфраструктура.

Почему так удобно именно для сравнения:

– один контракт OpenAPI на всех,

– одни e2e‑тесты на всех,

– проще переиспользовать модели, генераторы, утилиты,

– проще увидеть различия в коде рядом.

Мы договорились про:

– pnpm как менеджер пакетов,

– Turborepo как инструмент сборки/кеширования задач.

0.2.1. Договоримся о путях

Структура, которую мы будем использовать:

– /apps/frontend-next – Next.js (App Router)

– /apps/api-ts – TypeScript backend (NestJS)

– /apps/api-py – Python backend (FastAPI)

– /apps/api-java – Spring Boot + Kotlin

– /apps/api-go – Go + chi

– /packages/shared-contract – OpenAPI/DTO/генерация клиентов

– /infra – docker-compose, (позже – k8s/terraform при необходимости)

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

Важно: мы специально называем приложения одинаково предсказуемо (api-ts, api-py, …), чтобы скрипты, CI и документация были проще.

2.2. Turborepo: зачем он здесь

Turborepo полезен, когда:

– много проектов,

– есть повторяющиеся команды (lint, test, build),

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

Типичный подход:

– каждый проект в apps/ имеет свои команды,

– корневые команды запускают их все,

– turbo решает, что можно выполнить параллельно, а что нужно последовательно.

Например, логика может быть такая:

– сначала генерируем типы из OpenAPI в packages/shared-contract,

– потом бэкенды используют эти артефакты,

– потом фронт использует клиент.

Даже если вы не используете сложные графы задач – turbo всё равно упрощает запуск “всего репо”.

2.3. Общие правила репозитория

Чтобы репо не превратилось в свалку:

1) Все внешние сервисы (Postgres/Redis и т.п.) – в /infra и docker-compose.

2) Контракт API – в одном месте (/packages/shared-contract).

3) Каждый backend должен:

– подниматься командой dev,

– отдавать OpenAPI (если фреймворк умеет),

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

4) E2E тесты не знают, какой язык под капотом – им важен URL и контракт.

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

Самая важная идея книги: контракт важнее реализации.

Мы будем строить систему так, будто бэкенд – это “плагин”. Сегодня он на NestJS, завтра на FastAPI, послезавтра на Go. Если контракт не меняется – фронт и интеграции не должны страдать.

0.3.1. Что значит OpenAPI-first

OpenAPI-first означает:

1) Сначала описываем API в openapi.yaml.

2) На основе контракта:

– генерируем клиент для фронта,

– генерируем типы/DTO (где это уместно),

– валидируем, что запросы/ответы соответствуют схеме.

3) Реализации бэкенда обязаны соответствовать контракту.

Это дисциплина, которая резко снижает хаос:

– меньше “а давай добавим поле, а фронт потом как-нибудь догадается”,

– меньше разночтений между командами,

– проще писать e2e‑тесты.

Где лежит контракт и как он выглядит

Контракт кладём в:

– /packages/shared-contract/openapi.yaml

Внутри openapi.yaml мы описываем:

– базовую информацию (title, version),

– серверы (на локалке),

– пути (/health, /users, …),

– схемы данных (DTO),

– ошибки (единый формат).

Даже если в каждом бэкенде есть автогенерация OpenAPI (NestJS Swagger, FastAPI docs, Springdoc) – источником истины остаётся наш openapi.yaml.

Автогенерация полезна, но она часто:

– зависит от аннотаций и кода,

– по-разному описывает типы,

– может “уплывать” при рефакторингах.

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

Генерация клиентов и типов

Зачем это нужно:

– фронту нужны типы запросов/ответов,

– e2e‑тестам нужны типы,

– иногда удобно генерировать серверные интерфейсы/заготовки.

Что можно генерировать:

– TypeScript клиент (например, fetch‑клиент или axios‑клиент),

– TypeScript типы DTO,

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

В рамках книги важно не то, какой именно генератор вы выберете, а сам принцип:

– контракт обновили → артефакты пересобрали → всё компилируется/тестируется.

Хорошая практика: хранить сгенерированный код либо:

– в packages/shared-contract/dist (и не коммитить, генерировать в CI), либо

– коммитить в репозиторий (проще для новичков, меньше магии).

Для учебной книги часто удобнее второй вариант (видно, что получилось). Для промышленной разработки обычно выбирают первый (генерация в CI).

Валидация контракта в CI

Контракт должен проверяться автоматически, иначе он быстро перестанет быть “истиной”.

Минимальный набор проверок:

1) Линт OpenAPI – формат, обязательные поля, правила стиля.

2) Валидация схемы – файл реально соответствует OpenAPI версии 3.x.

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

Даже без сложных проверок уже полезно, чтобы CI падал, если openapi.yaml просто “сломался”.

0.3.5. Как связываем контракт и реализации

Чтобы это не осталось словами, нам нужны практические “крючки” в коде:

– Frontend использует сгенерированный клиент/типы. Если контракт поменяли – фронт компилится или падает, и это хорошо.

– E2E тесты используют контракт как основу: например, проверяют, что эндпоинты существуют, и ответы соответствуют схеме.

– Backend на каждом языке:

– реализует маршруты, перечисленные в контракте,

– возвращает формат ошибок, описанный в контракте,

– держит совместимость.

В следующих разделах мы начнём с самого простого: GET /health, затем добавим сущность (например, users или todos) и постепенно усложним.

Итог раздела: что у нас должно получиться к концу подготовки

К этому моменту у вас должно быть:

1) Готовое окружение:

– Git настроен,

– Docker работает,

– Node + pnpm работают,

– Python/Go/Java доступны (или через devcontainer).

2) Монорепозиторий с понятной структурой:

– apps/ для приложений,

– packages/shared-contract для контракта,

– infra для docker-compose,

– tests/e2e для общих тестов.

3) Принцип OpenAPI-first:

– есть openapi.yaml,

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

– есть проверка/валидация контракта.

Дальше мы начнём “первую реальную вертикаль”: инфраструктура (Postgres в compose), минимальные сервисы на каждом языке и первый общий e2e‑тест, который прогоняется одинаково для любого API.

Монорепозиторий и структура

В этой книге мы будем собирать один и тот же продукт, но с разными бэкендами: на TypeScript, Python, JVM и Go. Чтобы не утонуть в папках, скриптах и «а где это лежит?», мы сразу выберем понятную модель организации кода – монорепозиторий.

Монорепозиторий – это когда весь код проекта живёт в одном Git‑репозитории: фронтенд, несколько бэкендов, общие библиотеки, тесты и инфраструктура. Звучит как «большая куча», но при правильной структуре это, наоборот, делает проект спокойнее и предсказуемее.

Почему монорепозиторий удобен именно в этой книге

У нас будет несколько реализаций одного API. Они должны:

– иметь одинаковые эндпоинты и одинаковые форматы запросов/ответов;

– проходить одни и те же e2e‑тесты;

– использовать одни и те же договорённости по ошибкам, статус-кодам, структуре JSON.

Если каждую реализацию держать в отдельном репозитории, то почти всё усложняется:

– контракт API начинает жить в нескольких копиях;

– тесты дублируются и расходятся;

– инфраструктура (Postgres/Redis и т.п.) повторяется;

– сравнивать реализации сложнее – всё раскидано по разным местам.

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

Общая структура проекта

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

text

/apps/frontend-next

/apps/api-ts

/apps/api-py

/apps/api-java

/apps/api-go

/packages/shared-contract

/infra

/tests/e2e

Дальше разберём смысл каждой папки, и какие правила мы будем соблюдать.

apps/: приложения (то, что запускается)

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

/apps/frontend-next

Фронтенд на Next.js. Это «лицо» продукта и удобный способ быстро проверить, что API реально работает.

Что обычно лежит внутри:

– страницы и компоненты UI;

– клиент для API (чаще всего сгенерированный);

– настройки окружений (.env.local), базовый URL до API.

Главная договорённость: фронтенд не должен знать, какой именно бэкенд работает внутри. Он должен опираться на контракт: если API соответствует OpenAPI, фронтенд работает.

/apps/api-ts

Бэкенд на TypeScript (например, NestJS). Он будет полезен как «референс» для многих команд: TypeScript часто выбирают в компаниях, где много фронтенда.

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

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

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

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

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

/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.

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

– вы запускаете api-ts и гоняете e2e – всё зелёное;

– переключаете на api-go и гоняете те же e2e – тесты должны пройти без изменений.

Если тесты завязаны на конкретную реализацию – это плохие e2e.

Хорошие e2e завязаны на контракт.

Минимальные договорённости по именованию и портам

Чтобы всё собиралось без «магии», вводим простые правила:

1. У каждого бэкенда свой порт по умолчанию (например: 3001/3002/3003/3004).

Но порт всегда можно переопределить через переменную окружения.

2. У каждого бэкенда общий базовый префикс API (например, без префикса или /api – главное, чтобы одинаково везде).

3. Фронтенд читает API_BASE_URL из env и не «хардкодит» адрес.

4. E2E тесты читают E2E_BASE_URL (или аналог) – один параметр, чтобы тесты знали, куда стучаться.

Это мелочи, но они экономят огромное количество времени.

0.2.8. Инструменты, которые удобно поставить для работы с монорепо

Ниже – набор программ, которые заметно упрощают жизнь. Ничего “обязательного” здесь нет, но с ними будет легче.

Для работы с Git и кодом

– VS Code – универсальный редактор для всего монорепо.

– IntelliJ IDEA – очень удобна для Spring Boot/Gradle/Maven.

– Git client (по желанию) – если вам проще визуально смотреть историю и конфликты.

Для инфраструктуры

– Docker Desktop (macOS/Windows) или Docker Engine (Linux).

– Postman или Insomnia – быстро вручную дергать API (хотя у нас будет OpenAPI и тесты).

Для работы с API-контрактом

– Плагин OpenAPI для редактора (подсветка, подсказки, валидация).

– Любой HTTP клиент в IDE (в VS Code/JetBrains есть встроенные варианты).

Для языков

– Node.js (лучше через менеджер версий), плюс pnpm.

– Python (через pyenv/uv – как удобнее).

– JDK (например, 21) для JVM-проекта.

– Go (желательно фиксировать версию в проекте).

Что мы получаем в итоге

После того как структура задана, у нас появляется понятная картина:

– В apps/ лежат разные реализации, которые можно запускать по очереди.

– В packages/shared-contract лежит единый контракт API и генерация типов/клиентов.

– В infra/ лежит общая инфраструктура, которую не нужно дублировать.

– В tests/e2e лежат тесты, которые одинаково проверяют любой бэкенд.

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

Небольшая правка по ответам из предыдущего раздела

Перед новой главой уточним два момента, чтобы дальше не было путаницы.

Где лежит контракт API и почему он один?

В общем смысле вы правы: контракт – это соглашение. Но в нашем проекте это соглашение должно быть зафиксировано в коде в одном месте, иначе оно начнёт «плавать» между реализациями.

В монорепозитории книги контракт лежит здесь:

– /packages/shared-contract/openapi.yaml

Почему он один:

– единый источник правды: фронтенд, тесты и все бэкенды сверяются с одним файлом;

– нет расхождений «в TS так, а в Go чуть иначе»;

– проще развивать API: изменения проходят через одно место и проверяются автоматически.

Где будут e2e‑тесты и почему они не должны зависеть от конкретного языка?

В нашем проекте e2e‑тесты лежат в:

– /tests/e2e

Они не зависят от языка, потому что их цель – проверять поведение системы через HTTP, то есть:

– одинаковые URL и методы,

– одинаковые статус-коды,

– одинаковые тела ответов,

– одинаковые ошибки.

То, написан сервер на Python или Java, для e2e вообще не важно – важен контракт и фактическое поведение.

Что относится к apps/, а что – к packages/?