Backend Developer Handbook¶

Это рабочий справочник для backend-инженеров, пишущих Go-сервисы в KazMaps. Он описывает, как мы пишем код: от установки окружения до ревью pull request'а и отладки проблем в проде. Всё, что здесь описано — это текущий стандарт, а не обсуждение альтернатив.

Handbook предназначен для ежедневного использования. Если ты не знаешь, как оформить новый HTTP-endpoint, добавить миграцию, опубликовать Kafka-событие или отладить застрявший consumer — ответ должен быть здесь.

Структура handbook¶

docs/
├── index.md                   — эта страница
├── onboarding/                — первые шаги: установка, первый PR, локальный стек, ownership
├── conventions/               — правила: layout, Go-стиль, БД, события, HTTP, логирование, тесты,
│                                безопасность, ошибки, конфиг, shutdown, observability, коммиты/PR
├── patterns/                  — deep-dive по паттернам: outbox, CQRS, idempotent consumer, api composition
├── how-to/                    — короткие рецепты («как добавить endpoint», «как добавить миграцию»)
├── checklists/                — чеклисты для автора PR, ревьюера и запуска нового сервиса
├── troubleshooting/           — типовые проблемы и как их чинить
├── services-catalog.md        — каталог живых сервисов (owner, порт, события, HTTP API)
├── event-catalog.md           — каталог Kafka-событий (topic, publisher, payload, consumers)
├── architecture-overview.md   — обзор архитектуры
├── authentication-flow.md     — end-to-end auth: JWT, HMAC, Gateway → backend
└── glossary.md                — глоссарий терминов

В каждой подпапке есть свой README.md-индекс с кратким описанием каждой страницы:

conventions/README.md — индекс conventions.
patterns/README.md — индекс паттернов + когда использовать какой.
how-to/README.md — индекс how-to с группировкой daily-ops / data / security / observability.
troubleshooting/README.md — индекс runbook'ов + правило «сначала сюда, потом в чат».
checklists/README.md — индекс чеклистов + когда использовать какой.

С чего начать новичку¶

onboarding/01-setup.md — поставь Go, Docker, golangci-lint, migrate и остальной инструментарий.
onboarding/02-first-pr.md — пройди полный цикл: branch → code → test → PR → merge.
architecture-overview.md — пойми, какая у нас архитектура и какие паттерны используем.
onboarding/03-local-stack.md — подними локально полный стек через docker compose.
onboarding/04-who-owns-what.md — узнай, кто владеет каким сервисом, куда писать вопросы.

После онбординга держи открытыми две страницы:

conventions/project-layout.md — где что лежит в Go-сервисе.
checklists/pr-author.md — перед тем как запросить review.

Как пользоваться¶

Правила в conventions/ — обязательны. Если ты отклоняешься, это повод для обсуждения на ревью.
Рецепты в how-to/ — короткие пошаговые инструкции для типовых задач. Начинай с них, когда не уверен, с какого конца подступиться.
Чеклисты в checklists/ — пробегай глазами перед запросом ревью и перед включением прод-трафика на новый сервис.
troubleshooting/ — загляни сюда прежде чем писать в чат: вероятно, твоя проблема уже описана.

Примеры в handbook берутся из реального кода сервисов user, review, media, notification. Каждый сервис живёт в отдельном git-репозитории. Если видишь ссылку вида «в репозитории сервиса user, internal/handler/router.go» — открой этот путь в клоне соответствующего сервис-репо и смотри, как сделано.

Карта по задачам¶

Задача	Куда смотреть
Поставить инструменты, настроить IDE	`onboarding/01-setup.md`
Открыть первый PR	`onboarding/02-first-pr.md`
Понять, какая у нас архитектура и какие паттерны	`architecture-overview.md`
Разобраться в auth-потоке	`authentication-flow.md`
Разобраться с outbox паттерном	`patterns/outbox.md`
Разобраться с CQRS	`patterns/cqrs.md`
Идемпотентный consumer	`patterns/idempotent-consumer.md`
Композиция данных из нескольких сервисов	`patterns/api-composition.md`
Поднять локальный стек	`onboarding/03-local-stack.md`
Понять, где что лежит в сервисе	`conventions/project-layout.md`
Писать идиоматичный Go-код	`conventions/go-style.md`
Работать с Postgres и миграциями	`conventions/db-pgx.md`
Публиковать и потреблять Kafka-события	`conventions/events.md`
Собрать HTTP-endpoint	`conventions/http-api.md` + `how-to/add-http-endpoint.md`
Настроить логирование	`conventions/logging.md`
Писать тесты	`conventions/testing.md`
Обращаться с секретами, валидировать input	`conventions/security.md`
Обработать ошибки правильно	`conventions/error-handling.md`
Настроить конфиг сервиса	`conventions/configuration.md`
Graceful shutdown	`conventions/shutdown.md`
Инструментовать новый код	`conventions/observability.md`
Версионировать API	`conventions/api-versioning.md`
Кэшировать через Redis	`conventions/caching.md`
Добавить Go-dependency	`conventions/dependencies.md`
Wire'ить зависимости в main.go	`conventions/dependency-injection.md`
Локализовать контент (kk/ru/en)	`conventions/i18n.md`
Узнать что делает сервис X	`services-catalog.md`
Найти Kafka-event Y	`event-catalog.md`
Оформить коммит / PR	`conventions/commits-and-prs.md`
Добавить миграцию	`how-to/add-migration.md`
Добавить событие в Kafka	`how-to/add-kafka-event.md`
Добавить метрику и алерт	`how-to/add-metric-and-alert.md`
Запустить новый сервис	`how-to/add-new-service.md` + `checklists/production-ready.md`
Проверить новый HTTP-endpoint перед PR	`checklists/new-endpoint.md`
Сверить PR как ревьюер	`checklists/pr-reviewer.md`
Отладить outbox lag	`how-to/debug-outbox-lag.md`
Провернуть JWT-ключ	`how-to/rotate-jwt-key.md`
Читать логи в Loki	`how-to/read-logs.md`
Читать traces в Tempo	`how-to/read-traces.md`
Профилировать сервис	`how-to/profile-service.md`
Запустить load test	`how-to/load-test.md`
Миграция не применяется	`troubleshooting/migration-fails.md`
Тест висит	`troubleshooting/test-hangs.md`
Consumer застрял	`troubleshooting/kafka-consumer-stuck.md`
Расшифровать термин	`glossary.md`

Как устроены репозитории¶

Каждый сервис — отдельный git-репозиторий. Это не монорепо — единого корневого репо с сервисами-сиблингами не существует. Когда ты работаешь над сервисом, ты клонируешь именно его репо и работаешь внутри него:

user-service/          — репо: auth + профили
review-service/        — репо: отзывы + реакции
media-service/         — репо: загрузка и хранение медиа
notification-service/  — репо: push/email/sms
backend-docs/          — отдельный репо: этот handbook

Каждый сервис — самодостаточный Go-модуль со своим go.mod, Dockerfile, Makefile, docker-compose.yml и миграциями. У каждого свой жизненный цикл: отдельные pull request'ы, отдельные релизы, независимый деплой. Сервисы общаются через HTTP (internal endpoints) и Kafka (асинхронные события).

Общие технические абстракции (pgx-wrapper, shared DTO) пока живут в pkg/ внутри сервис-репо. Когда такой код стабилизируется (зафиксирован API, есть тесты, определены владельцы) — он выносится в отдельный репозиторий-библиотеку и подключается через Go-модули. До этого момента допускается копирование между сервисами; синхронизация — задача владельцев.

Как обновлять handbook¶

Handbook живёт в отдельном git-репозитории (backend-docs) и обновляется своими pull request'ами. Полный процесс — в CONTRIBUTING.md. Ключевые правила:

Любое изменение — через pull request. Прямых коммитов в main нет.
Требуется approve от lead-инженера backend-команды. Это не бюрократия: handbook определяет, как пишет код вся команда, поэтому правки проходят такой же ревью, как и production-код.
Меняешь правило — обнови и примеры. Если правишь conventions/db-pgx.md, убедись, что код-сниппеты остались корректными.
Нашёл расхождение между handbook и реальностью? Открой PR: либо подтяни код под handbook, либо обнови handbook. Расхождение — это баг.
Формат — Markdown с ATX-заголовками (#, ##, ###). Строки до 100 символов по возможности. Код-блоки с языковой пометкой (```go, ```sql).

Поддержка¶

Вопросы по правилам из handbook — пиши в канал backend-команды в мессенджере команды. Если вопрос повторяется — открой PR с уточнением в handbook.
Вопросы по конкретному сервису — смотри owner'а в onboarding/04-who-owns-what.md и пиши ему напрямую.
Нашёл ошибку в handbook — открывай PR сразу, не жди, пока кто-то ещё наткнётся на то же место.

Где смотреть публичные Go-гайды¶

Handbook не дублирует общеизвестные Go-гайды. Когда в правилах встречаешь ссылку на Effective Go или Uber Go Style Guide — открой их и прочитай. Конкретные проектные отклонения от этих гайдов описаны в conventions/go-style.md.

Локальный просмотр документации¶

Handbook рендерится через MkDocs Material. Для локального просмотра:

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# или .venv\Scripts\activate  # Windows

pip install -r requirements-docs.txt
mkdocs serve

Откроется http://localhost:8000 с hot-reload при правке файлов.

Production-сайт (https://backend-handbook.kazmaps.dev) собирается и деплоится автоматически через Cloudflare Pages при пуше в main. Сборка идёт той же командой mkdocs build.