Conventions

Нормативные правила «как писать код в наших сервисах». Reference-уровень: формат, API, структура. Если в PR что-то противоречит conventions — ревьюер ссылается на конкретный раздел отсюда.

Любой backend-инженер должен пройти по этим страницам один раз целиком; потом возвращаться за конкретной ссылкой.

Страницы

• project-layout — раскладка папок в сервис-репо, слои cmd//internal//pkg/, где что лежит.
• service-readme — обязательная структура README сервис-репо: заголовки, таблицы HTTP API и событий, CI-проверка.
• go-style — имена, ошибки, интерфейсы, контекст, горутины — Go-специфичные правила.
• http-api — chi-роутер, middleware stack, формат request/response, пагинация, /v1/* vs /internal/*.
• db-pgx — pgxpool, транзакции через InTx, миграции, индексы, sentinel-ошибки.
• events — Watermill, Kafka-топики, envelope, publisher/consumer middleware, outbox-workflow.
• logging — log/slog JSON, structured-поля, маскирование PII, log.FromCtx(ctx).
• testing — пирамида тестов, table-driven, testcontainers, gochannel, race detector.
• security — секреты, JWT, GatewayAuth, internal-токен, HMAC, ротация ключей.
• error-handling — sentinel’ы, fmt.Errorf("...%w", err), errors.Is/As, маппинг в HTTP.
• configuration — env-переменные, префиксы, Redacted-логирование, .env.example.
• shutdown — graceful shutdown, SIGTERM, errgroup, terminationGracePeriodSeconds.
• observability — три сигнала (logs, metrics, traces), correlation, OpenTelemetry, SLO-based alerts.
• slo-and-budget — SLI/SLO, error budget, multi-window burn-rate alerts, latency и freshness SLI.
• api-versioning — URL-versioning для REST, schema/topic versioning для Kafka, breaking vs non-breaking.
• caching — Redis cache-aside, TTL/jitter, инвалидация, stampede protection, failure modes.
• data-retention — soft-delete, TTL для технических таблиц, outbox/audit cleanup, archival, Redis/Kafka retention.
• dependencies — vetting Go-deps, upgrade flow, govulncheck, популярные choices.
• dependency-injection — конструкторная DI, порядок build’а в main.go, consumer-side interfaces.
• i18n — локализация user-facing контента: kk/ru/ en, fallback-chain, template-syntax, notification-шаблоны.
• commits-and-prs — формат commit-message, структура PR, что писать в description.

Когда использовать

• Пишешь новый код → открывай страницу по теме (HTTP, DB, события), читай правила, пиши код.
• Ревьюишь PR → ссылайся на конкретный раздел при замечаниях (см. conventions/http-api.md#порядок-middleware).
• Заводишь новый сервис → проходишь все страницы сверху вниз вместе с ../how-to/add-new-service.