Conventions

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

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

Страницы

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

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

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