Перейти к содержанию

Соглашение об именовании событий

Часть невозвратного фундамента (event-bus-concept.md, раздел 10): переделывать именование задним числом дорого, поэтому фиксируется сразу.

Форма subject'а

<сущность>.<событие>.v<N>
  • сущность — о чём факт (transcript, meeting, invoice).
  • событие — что произошло, в прошедшем времени (факт, не команда): ready, created, failed. Не create, не process.
  • v\<N> — мажорная версия схемы в subject-токене (раздел 7). Ломающее изменение = новый subject …​.v2, живущий рядом со старым.

Пример: transcript.ready.v1, transcript.ready.v2, invoice.issued.v1.

Крупная система может вырасти в <домен>.<сущность>.<событие>.v<N> (billing.invoice.issued.v1) — домен добавляется префиксом, форма не ломается.

Правила

  • Только нижний регистр, токены через точку, внутри токена — без точек и пробелов (при нужде -).
  • Subject — это факт о прошлом. Команды («сделай X») в шину не идут — это задача движка (тест принадлежности, раздел 6).
  • Никакого PII/секретов в subject'е — он светится в логах, метриках, дашбордах. Чувствительное — внутри payload.
  • Результат — тоже событие. Выход функции движка публикуется как самостоятельный факт (<сущность>.<событие>.v<N>), а не как «ответ».

Streams и consumers (JetStream)

  • Stream группирует subject'ы одного домена/сущности (напр. stream TRANSCRIPT ловит transcript.>). Персистентность и ретеншн настраиваются на уровне стрима.
  • Durable consumer именуется по участнику-потребителю, не по событию: <участник>-<назначение> (напр. bridge-inngest, analytics-ingest). Имя — это identity: по нему участника находят, мониторят лаг и явно удаляют при выводе (раздел 9), иначе остаётся осиротевший consumer с растущим pending.

Где это живёт

Каждый subject обязан быть описан в ../contracts/asyncapi.yaml со ссылкой на JSON Schema в ../contracts/schemas/. Subject без контракта — не существует.