Перейти к основному содержимому

Правила Документирования Событий

Payload И Snapshot​

  • Событие должно содержать полезный snapshot агрегата или объекта, а не только легковесный набор ids.
  • Consumers должны иметь возможность восстановить контекст события без синхронного запроса к source service.
  • Payload включает основной aggregate snapshot и связанные короткие snapshots.
  • Snapshot не должен включать secrets, access tokens, raw provider credentials, raw PII, document images и большие unbounded collections.
  • Для больших коллекций публикуются bounded snapshots.
  • Если событие связано с изменением, payload может включать Before и After snapshots или ChangedFields, но After snapshot обязателен.
  • Snapshot version версионируется вместе с event payload.
  • Payload и snapshot описываются таблицами полей: имя, тип, обязательность, описание, источник значения, совместимость.
  • Nested payload models описываются отдельными таблицами в файле события.
  • Для enum полей события перечисляются значения; boolean flags не используются вместо расширяемых статусов.
  • Типы object, json, payload, metadata, context, attributes, settings запрещены без полной typed модели.
  • Если событие ссылается на справочник, payload содержит id записи handbook (CountryId/CurrencyId/LanguageId — short, RegionId/CityId — long) и при необходимости snapshot-модель справочника (CurrencySnapshot/CountrySnapshot/RegionSnapshot/CitySnapshot, дом — handbook/domain/snapshots.md); события с денежными суммами несут CurrencyId + CurrencySnapshot. CurrencyCode, LanguageCode, CountryCode не используются как ключ события.
  • ChangedFields описывается typed моделью ChangedFieldEntry с допустимыми именами полей, старым/новым masked value и типом изменения; произвольный map запрещен.

Источник и атомарность публикации​

  • В событии указывается операция-источник: API method, domain command, event consumer, callback или background job.
  • Событие публикуется атомарно со сменой состояния источника: факт изменения и публикация события фиксируются в одном согласованном изменении.
  • Если событие публикуется после state transition, указывается From и To status в payload или snapshot.
  • Event key выбирается так, чтобы сохранить ordering внутри aggregate: обычно TenantId + AggregateId.
  • Event payload не должен требовать синхронного запроса в producer service для базовой обработки consumer-ом.

Consumers И Side Effects​

  • Для каждого consumer указывается сервис, потребляющее поведение, side effects, idempotency key и expected latency.
  • Если consumer обновляет read model, cache или search index, это описывается явно.
  • Если consumer может вызывать внешний provider, указывается retry policy, timeout и dead-letter behavior.
  • Если у события пока нет потребителей, раздел «Потребители» опускается или ограничивается краткой пометкой, что событие публикуется как публичный контракт.

Observability​

  • Producer пишет log при публикации события и при publish failure/retry.
  • Consumer пишет log при получении, duplicate detection, successful handling и controlled failure.
  • Метрики минимум: publish latency, consume latency, error rate, throughput, DLQ count.
  • Trace переносит correlationId, causationId, eventId, tenantId.

Совместимость​

  • Новые поля добавляются как optional.
  • Breaking changes требуют новой версии события.
  • Consumers должны безопасно игнорировать неизвестные optional поля.
  • Unknown enum value должен иметь explicit fallback или приводить к controlled failure.

Обратные ссылки​

Автоссылки: где используется этот документ.