Рекомендации по формату, семантике и эволюции событий в Kafka.

Формат

• Ключ сообщения — идентификатор агрегата (user_id, account_id и т.д.) для партиционирования и идемпотентности потребителей.
• Тело — JSON с полями: event_type, version, occurred_at, payload. Тип события однозначно определяет структуру payload.
• Именование — event_type в UPPER_SNAKE_CASE; топики — домен.агрегат.events (например, identity.user.events).

Семантика

• События описывают факт, уже произошедший в системе; прошлое время (UserCreated, PasswordChanged).
• Payload содержит минимум данных, необходимых потребителям; без избыточного копирования всей агрегатной модели.
• Producer — единственный владелец топика; потребители не пишут обратно в тот же топик.

Обратная совместимость

• Добавление новых полей в payload — обратно совместимо (потребители игнорируют неизвестные поля).
• Удаление полей или смена типа — несовместимо; новая версия события (event_type_v2) или новый топик с периодом поддержки старого.
• При миграции — период dual-write и постепенный переход потребителей.

Связанные страницы

• Event Schema Catalog — каталог топиков и схем
• Event Flow — поток событий
• Event-Driven Patterns — реализация (Outbox, потребители)