← Все статьи

AsyncAPI для события «Заказ создан»: контракт от канала до payload

· 8 мин чтения

Пошаговая сборка контракта AsyncAPI 3.0 для события «Заказ создан»: структура сообщения, схема данных, каналы и правила версионирования. Пример готов к использованию в редакторе.

Команда разработки сервиса заказов опубликовала первое сообщение в очередь, но служба доставки получила данные в неверном формате, а аналитика не смогла сопоставить событие с базовой таблицей. Причина проста: между производителем и потребителями отсутствовал формальный контракт. В распределённых системах асинхронная коммуникация требует явного соглашения о структуре данных, так как отсутствие обратной связи в реальном времени маскирует несовпадения до момента критического сбоя. AsyncAPI — это спецификация для описания API событий, аналогичная OpenAPI для REST. Она позволяет зафиксировать, какие события существуют, какой транспорт используется и какова точная структура передаваемых данных.

Выбор версии спецификации

AsyncAPI имеет несколько версий: 2.x и 3.x. Версия 2.x основана на JSON Schema Draft 7, тогда как 3.x использует JSON Schema 2020-12. Для нового проекта рекомендуется использовать версию 3.0, так как она поддерживает более строгие типы данных и улучшает совместимость с современными инструментами генерации кода. Разница между версиями существенна: например, в 3.0 поле nullable работает иначе, чем в 2.x, где оно было частью расширения. При миграции с 2.0 на 3.0 необходимо внимательно проверять совместимость схем, особенно если используются сложные объединения типов (union types). В данном примере мы будем использовать AsyncAPI 3.0.

Структура документа

Документ AsyncAPI состоит из четырёх основных частей: метаинформация, каналы (channels), компоненты и операции. Метаинформация включает версию спецификации, название API и описание. Каналы определяют, куда отправляются события и откуда принимаются. Компоненты содержат переиспользуемые элементы: схемы сообщений, параметры, безопасности. Операции описывают направление взаимодействия: публикация (publish) или подписка (subscribe).

Для события «Заказ создан» нам нужен один канал публикации. Потребители будут подписаны на этот канал. Важно разделить каналы по логике: один канал для создания заказа, другой для изменения статуса, третий для отмены. Это позволяет потребителям подписываться только на те события, которые им нужны, снижая нагрузку и сложность обработки.

Описание канала и транспорта

Ниже приведён самостоятельный документ AsyncAPI 2.6.0. Он описывает публикацию со стороны сервиса заказов. Блоки schemas и messages в следующих разделах рассматриваются отдельно, но в полном документе располагаются внутри components.

Канал в AsyncAPI привязывается к конкретному транспорту. Поддерживаются Kafka, RabbitMQ, MQTT, WebSocket, AMQP и другие. Выбор транспорта влияет на синтаксис адресации. Для Kafka канал определяется топиком, для RabbitMQ — очередью и обменником. В примере мы используем Kafka, так как он обеспечивает упорядоченность сообщений внутри партиции и высокую пропускную способность, что важно для высоконагруженных систем заказов.

asyncapi: '2.6.0'
info:
  title: События заказов
  version: '1.0.0'
defaultContentType: application/json
servers:
  production:
    url: broker.example.com:9092
    protocol: kafka
channels:
  order.created:
    description: Событие о создании нового заказа
    publish:
      operationId: onOrderCreated
      message:
        $ref: "#/components/messages/orderCreated"
components:
  schemas:
    OrderCreatedPayload:
      type: object
      required:
        - orderId
        - createdAt
        - totalAmountCents
      properties:
        orderId:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        createdAt:
          type: string
          format: date-time
          example: "2026-03-15T10:30:00Z"
        customerEmail:
          type: string
          format: email
        totalAmountCents:
          type: integer
          minimum: 0
          example: 15000
        items:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - productId
              - quantity
              - priceCents
            properties:
              productId:
                type: string
              quantity:
                type: integer
                minimum: 1
              priceCents:
                type: integer
                minimum: 0
  messages:
    orderCreated:
      name: Order Created Event
      title: Заказ создан
      contentType: application/json
      headers:
        type: object
        properties:
          correlationId:
            type: string
            format: uuid
          publishedAt:
            type: string
            format: date-time
          schemaVersion:
            type: integer
            default: 1
      payload:
        $ref: "#/components/schemas/OrderCreatedPayload"

Имя канала order.created следует конвенции «сущность.действие». Это делает контракт читаемым и предсказуемым. Атрибут operationId уникален во всём документе и используется генераторами кода для создания методов обработчиков.

Схема сообщения и данных

Сообщение (message) в AsyncAPI содержит метаданные (headers) и тело (payload). Тело описывается через JSON Schema. Для события «Заказ создан» payload должен содержать идентификатор заказа, дату создания, список позиций и сумму. Важно указать типы данных точно: идентификаторы — строки UUID, суммы — числа с фиксированной точностью, даты — ISO 8601.

Частая ошибка — использование типа string для сумм денег. Это приводит к ошибкам округления при арифметических операциях. Вместо этого следует использовать integer для копеек или number с ограничением multipleOf: 0.01. В учебных целях мы будем использовать integer для копеек, что является наиболее безопасным подходом для финансовых операций.

schemas:
  OrderCreatedPayload:
    type: object
    required:
      - orderId
      - createdAt
      - totalAmountCents
    properties:
      orderId:
        type: string
        format: uuid
        example: "550e8400-e29b-41d4-a716-446655440000"
      createdAt:
        type: string
        format: date-time
        example: "2026-03-15T10:30:00Z"
      customerEmail:
        type: string
        format: email
      totalAmountCents:
        type: integer
        minimum: 0
        example: 15000
      items:
        type: array
        minItems: 1
        items:
          type: object
          required:
            - productId
            - quantity
            - priceCents
          properties:
            productId:
              type: string
            quantity:
              type: integer
              minimum: 1
            priceCents:
              type: integer
              minimum: 0

Поле items является массивом объектов. Каждому элементу массива требуется уникальный идентификатор позиции? Нет, если позиция однозначно определяется парой productId и количеством, отдельный ID позиции не обязателен. Однако, если в будущем потребуется поддержка скидок на уровне позиции, лучше добавить поле lineItemId. Пока мы оставляем схему минимально достаточной.

Версионирование событий

События, в отличие от REST API, сложнее версионировать, так как старые сообщения могут оставаться в очереди длительное время. Есть три основные стратегии версионирования событий:

  • Номер версии в имени канала (v1.order.created). Простая, но громоздкая стратегия. Требует создания новых каналов для каждого изменения.
  • Поле version в payload ({"version": 1, ...}). Потребитель проверяет версию и применяет соответствующую логику обработки. Гибче, но требует поддержки нескольких версий в коде.
  • Эволюция схемы (schema evolution). Добавление необязательных полей без изменения номера версии. Работает, если новые поля имеют значения по умолчанию.

Для события «Заказ создан» добавление нового поля, например discountCode, можно реализовать через эволюцию схемы, если это поле необязательное. Существующие потребители просто игнорируют новое поле. Если же изменение затрагивает семантику (например, смена формата даты), необходимо ввести новую версию. Рекомендуется комбинировать подходы: малые изменения — через эволюцию, крупные — через новую версию канала или поля version.

Метаданные сообщения

Помимо payload, сообщение может содержать заголовки (headers). Они полезны для передачи служебной информации: кореляционный ID, временная метка публикации, версия схемы. Эти данные не должны попадать в бизнес-логику, но необходимы для трассировки и диагностики.

messages:
  orderCreated:
    name: Order Created Event
    title: Заказ создан
    contentType: application/json
    headers:
      type: object
      properties:
        correlationId:
          type: string
          format: uuid
        publishedAt:
          type: string
          format: date-time
        schemaVersion:
          type: integer
          default: 1
    payload:
      $ref: "#/components/schemas/OrderCreatedPayload"

Поле correlationId позволяет связать событие с исходным запросом пользователя. Если пользователь создал заказ через веб-интерфейс, correlationId совпадает с ID HTTP-запроса. Это критически важно для отладки: если склад не получил уведомление, можно проследить путь от браузера до брокера по этому идентификатору.

Сравнение стратегий версионирования

Выбор стратегии версионирования зависит от частоты изменений и требований к совместимости. Таблица ниже сравнивает три основных подхода с точки зрения сложности управления, скорости реакции на изменения и рисков для потребителей.

СтратегияСложность управленияСовместимость назадРиск поломки потребителей
Версия в имени каналаВысокая (новые топики)Да (раздельные потоки)Низкий
Поле version в payloadСредняя (логика ветвления)Да (если поддерживать старые версии)Средний
Эволюция схемыНизкая (добавление полей)Да (для добавлений)Низкий (при соблюдении правил)

Для большинства событий жизненного цикла заказа (создание, оплата, отправка) оптимальна стратегия эволюции схемы для мелких изменений и поле version для крупных структурных перестроений. Использование отдельных каналов для каждой версии быстро приводит к хаосу в инфраструктуре брокера.

Правила идемпотентности

Гарантии доставки зависят от брокера, конфигурации и границы подтверждения. В выбранном учебном профиле допускается доставка как минимум один раз, поэтому получатель должен учитывать повтор сообщения. Потеря подтверждения после обработки может вызвать повторную доставку. Сам факт использования брокера не устанавливает эту гарантию для любой системы.

Для учебного события повтор распознаётся по согласованной идентичности. Проверка существования заказа отдельно от вставки недостаточна при конкуренции; создание защищают уникальным ограничением и согласованной транзакцией либо другим достаточным механизмом. Внешние эффекты не становятся идемпотентными только из-за локальной транзакции. Они требуют собственного ключа или процедуры сверки.

Важно различать атомарность базы данных и идемпотентность внешней логики. Транзакция гарантирует, что либо все изменения применены, либо ни одного. Идемпотентность гарантирует, что повторное применение одних и тех же изменений не меняет конечное состояние. Оба механизма необходимы, но решают разные проблемы.

Проверка контракта

Спецификация AsyncAPI — это статический документ. Чтобы убедиться, что реализация соответствует контракту, необходимо проводить валидацию. Инструменты вроде asyncapi-cli позволяют проверить синтаксис файла и выполнить dry-run генерации кода. Более глубокая проверка — сравнение реальной структуры сообщений в брокере с схемой из спецификации.

Для этого можно настроить консьюмера, который читает сообщения из тестовой очереди и валидирует их против JSON Schema из AsyncAPI. Если сообщение не проходит валидацию, оно направляется в dead-letter queue (DLQ), а ошибка логируется. Это позволяет обнаруживать несоответствия до того, как они повлияют на производственные данные.

Типичные ошибки

  • Неясное назначение поля — поле amount без указания валюты. Всегда указывайте валюту отдельно или используйте код валюты в названии поля.
  • Отсутствие обязательных полей — если orderId отсутствует, событие бесполезно. Убедитесь, что все ключевые поля отмечены как required.
  • Изменение формата без уведомления — смена формата даты из Unix timestamp в ISO 8601 ломает старых потребителей. Используйте версионирование.
  • Слишком сложные схемы — вложенные объекты глубже трех уровней затрудняют чтение и поддержку. Разбивайте большие события на несколько более простых.
  • Игнорирование метаданных — отсутствие correlationId делает невозможным отслеживание сквозной цепочки вызовов.

Интеграция с процессом разработки

Спецификация AsyncAPI должна храниться в репозитории вместе с кодом. Изменения в контракте проходят ревью так же, как изменения в коде. Генерация клиентского кода из спецификации автоматизирует создание DTO и интерфейсов. При каждом изменении спецификации запускайте CI-пайплайн, который проверяет совместимость с предыдущей версией и предупреждает о breaking changes.

Это превращает асинхронную интеграцию из «магии» в управляемый процесс. Аналитик может открыть редактор AsyncAPI, вставить подготовленный YAML-код и доработать его под конкретные требования проекта. Подробности о выборе паттернов событийной архитектуры изложены в статье Event-Driven Patterns.