← Все статьи

Структура события: какие метаданные нужны кроме бизнес-данных

· 7 мин чтения

Разбор структуры события: почему business payload недостаточно, какие метаданные обязательны в envelope, примеры JSON и правила версионирования для асинхронных систем.

Когда разработчик пишет первый обработчик события, он часто смотрит только на поле data. Там лежит заказ, пользователь или транзакция. Но при первом же инциденте выясняется, что непонятно, кто это событие опубликовал, когда именно оно произошло и как правильно интерпретировать данные, если схема изменилась. Бизнес-логика работает, но операционная наблюдаемость отсутствует. Чтобы события были полезны не только для текущего потребителя, но и для отладки, аудита и эволюции схемы, им нужен структурированный контейнер — envelope.

Почему бизнес-данных недостаточно

Чистый объект данных, например JSON-представление заказа, отвечает на вопрос «что произошло?». Однако в распределённой системе возникает ряд дополнительных вопросов, которые этот объект не решает:

  • Происхождение: какой сервис или процесс выпустил это сообщение? Если три сервиса публикуют «OrderCreated», как отличить их?
  • Момент времени: когда событие произошло в источнике, а не когда оно попало в брокер? Разница критична для причинно-следственных связей.
  • Версия схемы: как понять, что поле total теперь означает сумму в рублях, а не в центов, или что добавилось новое необязательное поле?
  • Корреляция: как связать это событие с другими событиями одного процесса (например, создание заказа и последующая оплата)?

Без этих метаданных каждый потребитель вынужден придумывать собственные соглашения, что приводит к фрагментации архитектуры и сложностям при миграциях. Envelope унифицирует эти аспекты, отделяя транспортные и организационные атрибуты от чистого бизнес-нагрузки.

Анатомия стандартного Envelope

Envelope — это верхний уровень JSON-объекта, который оборачивает полезную нагрузку. В большинстве промышленных практик (включая рекомендации Apache Avro, Protocol Buffers и спецификации AsyncAPI) он содержит набор обязательных полей. Ниже приведён типовой набор метаданных, который рекомендуется включать в каждое событие.

ПолеТипНазначениеПример значения
idUUID v4Уникальный идентификатор конкретного экземпляра события. Используется для идемпотентности."550e8400-e29b-41d4-a716-446655440000"
typestringЛогическое имя события. Должно быть стабильным и описывать факт, а не действие."order.created.v1"
versionintegerВерсия схемы полезной нагрузки. Позволяет поддерживать совместимость.1
sourceobject/stringИдентификатор сервиса или приложения, создавшего событие.{ "service": "orders", "instance": "pod-abc123" }
occurredAtISO 8601Момент времени, когда событие произошло в бизнес-системе."2023-10-27T10:15:30.123Z"
correlationIdUUID v4ID сквозного процесса. Один и тот же ID во всех событиях одного бизнес-процесса."f47ac10b-58cc-4372-a567-0e02b2c3d479"
causationIdUUID v4ID родительского события, которое привело к созданию данного."550e8400-e29b-41d4-a716-446655440000"

Эти поля образуют «каркас» сообщения. Они должны присутствовать даже если бизнес-данные пусты. Наличие id позволяет брокеру или потребителю отслеживать дубликаты, а correlationId превращает поток независимых событий в трассируемую цепочку действий.

Практический пример: Order Created

Рассмотрим конкретный случай. Сервис «Заказы» публикует событие о создании нового заказа. Мы будем использовать версию схемы 1. Полезная нагрузка (payload) содержит только бизнес-поля: ID заказа, клиента и сумму.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "order.created.v1",
  "version": 1,
  "source": {
    "service": "order-service",
    "environment": "production"
  },
  "occurredAt": "2023-10-27T10:15:30.123Z",
  "correlationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "causationId": null,
  "payload": {
    "orderId": "ORD-2023-998877",
    "customerId": "CUST-456789",
    "amount": 1500.00,
    "currency": "USD"
  }
}

Обратите внимание на несколько нюансов. Во-первых, type включает суффикс версии v1. Это упрощает фильтрацию в брокерах, где топик может содержать несколько версий одного события. Во-вторых, causationId равно null, так как создание заказа является корнем процесса (root event). В-третьих, source указывает не просто имя сервиса, но и окружение, что полезно при параллельном существовании staging и production потоков в одном кластере.

Когда клиент оплачивает заказ, сервис «Платежи» публикует событие payment.completed.v1. В этом случае correlationId будет таким же, как в событии создания заказа, а causationId укажет на ID события order.created. Это позволяет восстановить полную историю: кто инициировал процесс и какие шаги последовали.

Версионирование схем и совместимость

Главная причина, по которой version находится в envelope, а не в имени типа, — поддержка обратной и прямой совместимости. В асинхронных системах производитель и потребитель могут обновляться независимо. Если производитель начинает отправлять новые поля, старый потребитель не должен падать. Если потребитель ожидает новые поля, а производитель еще их не присылает, потребитель должен обрабатывать отсутствие этих полей корректно.

  • Backward compatibility: новые версии схемы должны быть понятны старым потребителям. Добавление необязательных полей допустимо. Удаление или изменение типа существующих полей — нет.
  • Forward compatibility: старые версии схемы должны быть понятны новым потребителям. Обычно достигается тем, что новые потребители знают о старых форматах или имеют логику обработки legacy-данных.

При изменении схемы, нарушающем обратную совместимость (например, смена типа поля amount с числа на строку), необходимо увеличить номер версии. Новое событие получит type: "order.created.v2". Потребитель, настроенный на v1, просто проигнорирует сообщения v2 (или обработает ошибку, если такая логика предусмотрена), но не сломается. Это позволяет мигрировать систему постепенно: сначала подключают потребителей v2, затем переключают производителей, и наконец удаляют поддержку v1.

Корреляция и причинно-следственные связи

Поля correlationId и causationId решают проблему наблюдаемости в сложных оркестровых сценариях. Представьте процесс оформления заказа, который включает создание заказа, проверку кредитного лимита, резервирование товара и оплату. Каждое из этих событий происходит в разных сервисах и может иметь разную задержку.

correlationId генерируется один раз в начале процесса (часто в API Gateway или первом сервисе) и пробрасывается во все последующие события. Он служит «нитью Ариадны», позволяющей собрать все события одного заказа в единую временну́ю шкалу. Инструменты мониторинга (Grafana, ELK Stack) используют этот ID для агрегации логов и метрик.

causationId уточняет непосредственную причину. Если событие оплаты вызвано успешным резервированием товара, то causationId события оплаты равен ID события резервирования. Это создает дерево зависимостей, которое полезно для отладки: если процесс завис, можно найти «узловое» событие, после которого цепочка прервалась.

Безопасность и чувствительные данные

Envelope не должен содержать секретов, паролей, токенов доступа или персональных данных, не связанных напрямую с идентификацией бизнес-объекта. Если событие содержит PII (Personally Identifiable Information), такие данные должны быть либо анонимизированы, либо защищены средствами шифрования на уровне транспорта (TLS) и брокера.

Важно различать source и аутентификационные данные. Поле source идентифицирует приложение, но не предоставляет прав доступа. Права доступа к теме (topic) или очереди (queue) должны управляться механизмами авторизации брокера (ACL), а не данными внутри сообщения. Включение JWT-токена в payload события считается плохой практикой, так как токены имеют срок действия и могут стать недействительными к моменту потребления, а также увеличивают размер сообщения.

Инструментарий и валидация

Ручное поддержание структуры событий приводит к ошибкам. Рекомендуется использовать формализованные языки описания схем. Для JSON-событий чаще всего используют JSON Schema или Avro. Эти инструменты позволяют автоматически проверять соответствие сообщения структуре перед отправкой в брокер.

В контексте helper-sa можно открыть редактор AsyncAPI, чтобы описать каналы и сообщения. AsyncAPI поддерживает ссылки на JSON Schema для определения структуры payload и envelope. Это обеспечивает единый источник истины: разработчики видят контракт, а тестировщики могут генерировать мок-данные на основе этой схемы.

Также полезно настроить валидацию на стороне брокера (если он поддерживает плагины) или в промежуточном слое (sidecar). Если сообщение не проходит валидацию по схеме, оно должно попадать в «dead letter queue» (DLQ) с указанием причины ошибки, а не теряться бесследно.

Типичные ошибки в проектировании Envelope

  • Динамические типы: использование общего типа "event" для всех событий. Это делает невозможной точную маршрутизацию и фильтрацию. Тип должен быть уникальным для каждого факта.
  • Отсутствие ID: попытка использовать комбинацию полей (например, orderId + timestamp) как уникальный идентификатор. Это хрупко и не гарантирует глобальную уникальность. Всегда используйте UUID.
  • Времена в Unix Epoch: хранение времени как целого числа. Хотя это компактно, ISO 8601 человекочитаемо и стандартно. Unix Epoch требует знания часового пояса для интерпретации, что увеличивает риск ошибок.
  • Смешение версий в одном типе: отправка событий v1 и v2 с одним и тем же type, надеясь, что потребитель разберется по наличию полей. Это ломает контракты. Версия должна быть частью идентификатора события.
  • Избыточные метаданные: включение в envelope данных, которые доступны только через внешний запрос (например, полное имя пользователя). Envelope должен быть самодостаточным для базовых операций, но не дублировать всю базу данных.

Итог

Структура события — это фундамент асинхронной архитектуры. Правильно спроектированный envelope с обязательными метаданными (id, type, version, source, time, correlationId) превращает хаотичный поток байтов в управляемую, наблюдаемую и эволюционирующую систему коммуникации. Он позволяет отделять бизнес-логику от транспортных проблем, обеспечивает безопасное версионирование и дает возможность трассировать сложные процессы во времени. Внедрение таких стандартов с самого начала разработки значительно снижает стоимость поддержки системы в будущем.