Каналы и операции

Channels — каналы

channels — объект «адрес канала → описание канала». Адрес — это имя топика, очереди, маршрутизирующего ключа или путь; он может содержать параметры в фигурных скобках.

channels:
  orders.created: ...
  orders/{orderId}/status: ...
  user.{userId}.notifications: ...

Channel Item

Поле	Описание
description	Описание канала.
subscribe	Операция: приложение отправляет сообщения в канал (другие подписываются на них).
publish	Операция: приложение принимает сообщения из канала (другие публикуют их).
parameters	Параметры адреса канала.
bindings	Настройки канала, специфичные для протокола.
$ref	Ссылка на описание канала в другом месте.

Как понимать publish и subscribe

В AsyncAPI 2.x названия операций описаны с точки зрения того, кто работает с приложением:

Операция в документе	Что делает само приложение	Что могут делать другие
subscribe	отправляет сообщения	подписаться и получать их
publish	принимает сообщения	публиковать их для приложения

Например, сервис заказов, который рассылает событие «заказ создан», описывает канал orders.created операцией subscribe; а команду «отменить заказ», которую он получает от других, — операцией publish. Эта «перевёрнутая» логика — частый источник ошибок; в AsyncAPI 3.0 её заменили явными действиями send и receive.

Operation — операция

Поле	Описание
operationId	Уникальный идентификатор операции; генераторы кода делают из него имя метода.
summary, description	Краткое и подробное описание.
tags	Теги.
externalDocs	Внешняя документация.
bindings	Настройки операции для протокола (например, группа потребителей Kafka).
traits	Общие части операций (Operation Trait), которые сливаются с операцией.
message	Сообщение операции или несколько сообщений через oneOf.

asyncapi: 2.6.0
info:
  title: Сервис заказов
  version: 1.0.0
channels:
  orders.created:
    description: События о созданных заказах
    subscribe:
      operationId: publishOrderCreated
      summary: Сервис сообщает о созданном заказе
      message:
        $ref: '#/components/messages/OrderCreated'
  orders.commands:
    description: Команды для сервиса заказов
    publish:
      operationId: handleOrderCommand
      summary: Сервис принимает команды
      message:
        oneOf:
          - $ref: '#/components/messages/CancelOrder'
          - $ref: '#/components/messages/ConfirmOrder'
components:
  messages:
    OrderCreated:
      name: OrderCreated
      payload:
        type: object
        required: [orderId]
        properties:
          orderId:
            type: string
            format: uuid
    CancelOrder:
      name: CancelOrder
      payload:
        type: object
        properties:
          orderId:
            type: string
          reason:
            type: string
    ConfirmOrder:
      name: ConfirmOrder
      payload:
        type: object
        properties:
          orderId:
            type: string

Parameters — параметры канала

Параметр описывает часть адреса канала в фигурных скобках.

Поле	Описание
description	Описание параметра.
schema	Схема значения (обычно строка с ограничениями).
location	Выражение, откуда берётся значение в сообщении, например $message.payload#/user/id.

channels:
  user.{userId}.notifications:
    parameters:
      userId:
        description: Идентификатор пользователя
        schema:
          type: string
          format: uuid
        location: $message.payload#/userId
    subscribe:
      message:
        payload:
          type: object
          properties:
            userId:
              type: string
            text:
              type: string

Operation Traits — общие части операций

Trait позволяет вынести повторяющиеся поля (например, bindings Kafka) и подключить их к нескольким операциям через traits. Значения самой операции имеют приоритет над значениями trait.

components:
  operationTraits:
    kafkaConsumer:
      bindings:
        kafka:
          groupId:
            type: string
            enum: [orders-service]
channels:
  orders.commands:
    publish:
      traits:
        - $ref: '#/components/operationTraits/kafkaConsumer'
      message:
        payload:
          type: object