Глоссарий¶
Проектные и технические термины, которые встречаются в handbook и в коде. Если термин здесь — значит, он используется в текущей кодовой базе.
A¶
Advisory lock — блокировка на уровне Postgres, не связанная с конкретной
строкой или таблицей. Используется в начале каждой миграции
(pg_advisory_xact_lock(hashtext(...))), чтобы два pod'а не применяли
миграции параллельно. Снимается автоматически при COMMIT/ROLLBACK.
Aggregate — сущность, к которой привязано событие. В outbox-таблице хранится
aggregate_type (например, "review") и aggregate_id (строка) — они
используются как ключ партиции в Kafka, чтобы события одной сущности
попадали в одну партицию и сохраняли порядок.
C¶
CQRS — Command Query Responsibility Segregation: разделение модели на
команды (мутации) и запросы (чтение). У нас — через
watermill/components/cqrs, подключается точечно, когда в сервисе > 3
команд/событий на одну доменную модель. См.
architecture-overview.md.
Consent (в контексте notification-сервиса) — настройка каналов доставки
на пользователя: может быть push, email, sms, in-app. Включается/
выключается в профиле. Это техническая настройка, которую уважает
notification-сервис при отправке; проверяется на каждую отправку.
Context propagation — передача request-scoped данных (correlation id,
trace context, user id) через context.Context от HTTP-handler'а до
repository и дальше в event metadata.
Correlation-Id — ULID/UUID, идентифицирующий единую операцию, пересекающую
сервисы. Приходит в HTTP-заголовке X-Correlation-Id (или генерируется на
входе), пробрасывается в event metadata и логи, чтобы можно было
проследить цепочку через все сервисы по одному id.
D¶
Deduplicator — Watermill middleware, которое отклоняет повторные
сообщения с тем же Event-Id/Message.UUID. Реализация — через Redis
SETNX с TTL. Нужен для retry-idempotency.
DLQ (Dead Letter Queue) — топик, куда уходят сообщения, не обработанные
после всех retry. Имя — <topic>.dlq. В DLQ сообщения лежат, пока не
разобраны вручную.
E¶
Envelope — набор metadata-полей, которые сопровождают каждое событие:
Event-Type, Schema-Version, Correlation-Id, Source-Service,
Published-At, traceparent. Плюс Message.UUID как event id.
Event-Id — уникальный идентификатор события (Message.UUID в Watermill).
ULID. Используется для dedup.
Expand-contract migration — паттерн безопасных изменений схемы БД в три шага: expand (добавить колонку/таблицу nullable), backfill (заполнить данные), contract (навесить constraint / удалить старое). Каждый шаг — отдельная миграция. Позволяет делать rolling-deploy без downtime.
F¶
Forwarder — компонент из Watermill (components/forwarder), переносящий
сообщения из outbox-таблицы в Kafka. Заменяет собственный outbox-worker.
G¶
Gateway (API Gateway) — внешний edge-слой (Traefik): TLS
termination, routing по host/path, rate-limit, верификация JWT до
проксирования в сервис. Сервис сам JWT не валидирует, CORS-заголовки не
ставит — это задача Gateway. См.
conventions/security.md и
conventions/http-api.md.
GatewayAuth — HTTP-middleware сервиса, читающее подписанные
internal-заголовки от Gateway (X-User-Id, X-User-Role, HMAC-подпись),
валидирующее подпись и кладущее user-id/role в context.Context. Синоним
HeadersAuthenticator в старых обсуждениях — в новом коде и доке пиши
GatewayAuth. См. conventions/security.md.
H¶
Health check / Readiness probe — /healthz (liveness, 200 пока жив
процесс) и /readyz (readiness, проверяет БД/Redis/Kafka; возвращает 503
при shutdown). k8s/Gateway ориентируется на /readyz, чтобы решать,
роутить ли трафик. Детали —
conventions/http-api.md.
I¶
Idempotency — свойство handler'а: повторный вызов с теми же входными данными не даёт побочных эффектов. Для Kafka-consumer'ов обязательно, потому что at-least-once delivery неизбежно приводит к повторам.
Idempotent consumer — Kafka-consumer, у которого handler идемпотентен.
У нас двухуровневая реализация: Watermill Deduplicator middleware
(Redis SETNX по Message.UUID/Event-Id) плюс идемпотентность на
БД-уровне (unique constraint / UPSERT).
InTx — helper из pkg/db/db.go, который начинает транзакцию, вызывает
переданную функцию, commit'ит при success и rollback'ит при ошибке.
M¶
Migration — SQL-скрипт, переводящий схему БД из версии N в N+1. Живёт в
migrations/ как пара NNN_name.up.sql + NNN_name.down.sql.
Multipart upload (media-сервис) — загрузка больших файлов по частям: клиент получает upload session, отправляет chunks параллельно, закрывает сессию по завершении. Chunk'и хранятся во временном storage до commit'а сессии.
O¶
Outbox — таблица <schema>.outbox в БД сервиса. Публикация события в
Kafka идёт в две стадии: сначала row в outbox (атомарно с бизнес-tx), потом
forwarder переносит row в Kafka. Гарантирует отсутствие dual-write.
P¶
PgBouncer — connection pooler для Postgres. Используется между сервисами и Postgres в production-окружении. С точки зрения кода ничего не меняется: pool размерностью 20 у сервиса, но физических соединений к БД меньше.
PII — personally-identifiable information: email, phone, ФИО, токены, OAuth access/refresh, device id, IP-адрес. В открытом виде в логах / span attributes / payload событий запрещён — см. PII masking.
p95 (и другие percentile'и, p50/p99) — статистика латентности:
p95 = значение, ниже которого лежит 95% запросов. Считается из
histogram-метрики через histogram_quantile(0.95, ...) в PromQL. Базовый
SLI для HTTP-endpoint'а.
PII masking (маскирование PII) — правило, по которому personally-identifiable information (email, phone, ФИО, токены) не попадает в логи в открытом виде:
- email:
a***@example.com - phone:
+7 *** *** 42 31 - token: первые 4 +
...+ последние 4, либо полное опускание.
Вместо PII в structured-полях логируется user_id или другой непубличный идентификатор.
Poison queue — Watermill middleware, отправляющее сообщения, упавшие после всех retry, в DLQ.
pgxpool.Pool — connection pool из jackc/pgx/v5. Создаётся один раз в
main.go, передаётся в репозитории.
Publisher (Watermill) — интерфейс для публикации сообщений. У нас два: Kafka-publisher (для forwarder'а) и SQL-publisher (для outbox внутри бизнес-tx).
R¶
Retry middleware — Watermill middleware, повторяющее обработку сообщения при возврате error из handler'а. Конфигурация: 5 попыток, exponential backoff 500ms×2, с jitter.
Router (Watermill) — message.Router. Координатор consumer'а:
регистрирует handler'ы, применяет middleware, коммитит offset после успеха.
S¶
Saga — паттерн для распределённых транзакций с откатом через
компенсирующие шаги. В проекте не используется — подключаем, когда
появятся cross-service операции, требующие отката. См.
architecture-overview.md.
Schema-Version — версия формата payload'а события. Хранится в metadata
Schema-Version. Инкрементируется при breaking-изменении payload'а.
SLO (Service Level Objective) — целевое значение SLI (например, «p95
латентности < 300 мс 99% времени за 30 дней»). Алерты строятся по
multi-burn-rate модели поверх SLO. Конкретные SLO per-сервис живут в
infra-репо, не в handbook; conventions/observability.md
описывает только, как инструментовать.
Soft-delete — паттерн удаления через deleted_at TIMESTAMPTZ. Строка
не удаляется физически; все SELECT-запросы фильтруют WHERE deleted_at IS NULL.
Индекс делается частичным: CREATE INDEX ... WHERE deleted_at IS NULL.
Subscriber (Watermill) — интерфейс для подписки на сообщения. Kafka- subscriber для consumer-handler'ов, SQL-subscriber для forwarder'а (читает outbox).
T¶
Testcontainers — библиотека testcontainers-go для запуска
реальных зависимостей (Postgres, Kafka) в Docker из тестов. Используется
в integration-тестах репозиториев и forwarder'а.
Topic — Kafka topic. Формат имени — kazmaps.<service>.<entity>.<action>.
Transactional outbox — см. Outbox.
W¶
Watermill — библиотека pub-sub абстракций для Go (watermill.io). Стандартный способ работы с Kafka в проекте. Даёт Publisher/Subscriber, Router, middleware, DLQ, тест-инструменты.