Шаблон: спецификация Producer (Kafka, RabbitMQ)

Producer — компонент (микросервис, модуль, фоновый процесс), который формирует и публикует сообщение в брокер (топик Kafka, exchange/очередь RabbitMQ). Шаблон фиксирует контракт сообщения, параметры публикации и поведение при ошибках — для передачи в разработку и QA. Теория брокеров и паттернов EDA — в 03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events) и 03.05.06 Event-Driven Architecture; машиночитаемый контракт — 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf).

1. Назначение

Спецификацию Producer пишет системный аналитик; её читают разработка, QA, платформенная команда и владельцы 10.01.07 Шаблон спецификации Consumer (Kafka, RabbitMQ).

Шаблон закрывает четыре задачи:

• Контракт сообщения — key, headers, payload, сериализация; narrative дополняет JSON Schema / AsyncAPI, не дублирует учебник по брокеру.
• Поведение публикации — триггер, транзакционная согласованность (outbox), режим ожидания ack, политика повторов.
• Эксплуатация — метрики, алерты, судьба сообщения после исчерпания retry, безопасность канала.
• Трассировка — связь с FR/NFR, критериями приёмки и матрицей трассировки (10.01.15 Шаблон матрицы трассировки, 02.04.02 Критерии приёмки (Acceptance Criteria)).

Граница артефакта: Producer vs Outbox/Dispatcher

В шапке документа явно укажите Scope: «одна спека на Order Service (outbox + dispatcher + producer client)» или «Producer client только; outbox — платформенный ADR». Не смешивайте без явной декларации — иначе QA и разработка расходятся в границах задачи.

2. Когда использовать

Подходит, если:

• сервис публикует доменное событие или команду в Kafka или RabbitMQ;
• нужен человекочитаемый контракт с триггером, матрицей ошибок и NFR задержки/throughput;
• параллельно ведётся AsyncAPI / Schema Registry — markdown-спека добавляет семантику и governance.

Не подходит или требует дополнения, если:

• нужен обзор Kafka, RabbitMQ, acks, ISR — 03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events);
• описываете потребителя (offset, DLQ, идемпотентность обработки) — 10.01.07 Шаблон спецификации Consumer (Kafka, RabbitMQ);
• синхронный REST/gRPC — 10.01.04 Шаблон спецификации REST API;
• платформенные NFR (RPS, retention, audit) — 10.01.12 Шаблон нефункциональных требований (NFR), 08.02 Нефункциональные требования (НФТ) — классификация и стандарты;
• политика эволюции контрактов и согласование с consumer — 03.05.07 Управление версионированием API и жизненным циклом, 02.05.02 Управление изменениями (Change Control Board).

Входные условия: границы сервиса (03.01.04 Интерфейсы и интеграционные взаимодействия), термины и поля payload (10.01.14 Шаблон глоссария и словаря данных), формат JSON — 07.03 Основы XML, JSON, YAML.

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

Скопируйте блок в Confluence или Git. Поля обяз. нужны для утверждения; да* — при выполнении условия в скобках.

Правило распределения смысла между полями:

3.0. Шапка governance

3.1. Общая информация

3.2. Параметры брокера и топика/очереди

Kafka (дополнительные поля):

RabbitMQ (дополнительные поля):

Безопасность канала (чеклист, детали — 03.05.05 Безопасность API):

3.3. Структура сообщения

3.3.1. Ключ сообщения (Message Key) — Kafka

Логика выбора ключа: все события по одному заказу попадают в одну партицию; глобальный порядок между ключами не гарантируется.

Для RabbitMQ routing key задаётся в §3.2; отдельный message key не применяется.

3.3.2. Заголовки (Headers / Properties)

Маппинг по брокеру: в Kafka все поля — Record Headers. В RabbitMQ content-type и correlation-id — AMQP properties; traceId, tenantId, schema-version — таблица application_headers (headers). Не дублируйте одно значение в properties и headers без необходимости.

3.3.3. Тело сообщения (Value)

Схема (JSON Schema / Avro / Protobuf): храните в Git или Schema Registry; в спеке — $id, версия, ссылка на AsyncAPI.

Описание полей (согласовать с 10.01.14 Шаблон глоссария и словаря данных):

3.4. Условия отправки (триггер)

Распределение статусов outbox (зафиксируйте акторов — иначе QA и разработка расходятся):

Паттерн outbox и согласованность — 03.05.06 Event-Driven Architecture, 03.06.01 Архитектурные паттерны распределённых систем.

3.5. Обработка ошибок отправки

После исчерпания retry (outbox):

Распределённая компенсация (Saga) — отдельный уровень; не смешивать с локальным outbox без ADR — 03.05.06 Event-Driven Architecture.

3.6. Политика повторов (единственный нормативный блок)

3.7. Мониторинг и метрики

Имена и пороги согласуйте с NFR (10.01.12 Шаблон нефункциональных требований (NFR)) и стандартом observability-команды (префиксы, labels, SLO).

Алерт: producer_error_total > порога за 5 мин или producer_outbox_failed > 0 на prod.

3.8. Версионирование и обратная совместимость

3.9. Отладка (локально / staging)

Команды ниже — только локально или на staging; без prod credentials и без записи PII в shell history. Политика доступа — 03.05.05 Безопасность API, 08.07 Основы кибербезопасности для системного аналитика. Проверка доставки и потребления — 10.01.07 Шаблон спецификации Consumer (Kafka, RabbitMQ).

Kafka:

kafka-console-producer --broker-list localhost:9092 --topic orders.events \
  --property "parse.key=true" --property "key.separator=:"
> a1b2c3d4-e5f6-7890-abcd-ef1234567890:{"eventId":"...", "eventType":"OrderCreated", ...}

RabbitMQ (management plugin / rabbitmqadmin; key-less publish, routing key из §3.2):

rabbitmqadmin publish exchange=orders.topic routing_key=order.created.v1 \
  payload='{"eventId":"...", "eventType":"OrderCreated", ...}' \
  properties='{"delivery_mode":2, "content_type":"application/json"}'

3.10. Примечания и ограничения (NFR)

4. Пример заполнения

Scope: одна спека на Order Service — outbox writer + OutboxDispatcher + OrderEventsProducer.

Модель eventType: один топик orders.events, envelope с полем eventType; routing key не используется (Kafka).

Kafka: топик orders.events, key = orderId, acks=all, enable.idempotence=true.

Триггер: после COMMIT заказа и оплаты — запись в outbox; dispatcher polling 100 ms; публикует в sync-режиме (ждёт ack). SLA lag outbox → broker ≤ 500 ms.

RabbitMQ (тот же контракт payload, другой брокер): exchange orders.topic (type topic), routing key order.created.v1, delivery_mode=2, publisher confirms включены, ожидание confirm — да, таймаут 2000 ms. Exchange объявляет платформа (IaC). Key-less publish; упорядочивание — в спеке consumer.

Фрагмент JSON Schema (полная схема — в репозитории контрактов):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "OrderCreatedEvent",
  "type": "object",
  "properties": {
    "eventId": { "type": "string", "format": "uuid" },
    "eventType": { "const": "OrderCreated" },
    "occurredAt": { "type": "string", "format": "date-time" },
    "order": {
      "type": "object",
      "properties": {
        "orderId": { "type": "string", "format": "uuid" },
        "userId": { "type": "string", "format": "uuid" },
        "totalAmount": { "type": "number" },
        "currency": { "type": "string", "minLength": 3, "maxLength": 3 },
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "sku": { "type": "string" },
              "quantity": { "type": "integer", "minimum": 1 },
              "price": { "type": "number" }
            },
            "required": ["sku", "quantity", "price"]
          },
          "minItems": 1
        }
      },
      "required": ["orderId", "userId", "totalAmount", "currency", "items"]
    }
  },
  "required": ["eventId", "eventType", "occurredAt", "order"]
}

Пример сообщения (согласован со схемой и таблицей §3.3.3):

{
  "eventId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "eventType": "OrderCreated",
  "occurredAt": "2025-05-27T10:15:30Z",
  "order": {
    "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "totalAmount": 2590.00,
    "currency": "RUB",
    "items": [
      { "sku": "WIDGET-01", "quantity": 2, "price": 1000.00 },
      { "sku": "WIDGET-02", "quantity": 1, "price": 590.00 }
    ]
  }
}

Диаграмма последовательности (иллюстрация; нотация — 03.02.03 Диаграмма последовательности; сквозной BPMN — 10.01.08 Шаблон сквозной фичи (BPMN-процесс)):

sequenceDiagram
    participant Service as Order Service
    participant DB as База данных
    participant Outbox as Таблица outbox
    participant Dispatcher as Outbox Dispatcher
    participant Kafka as Apache Kafka

    Service->>DB: BEGIN; INSERT заказа; INSERT outbox
    DB-->>Service: COMMIT
    Note over Dispatcher: polling interval 100 ms
    Dispatcher->>Outbox: SELECT PENDING
    loop каждое событие
        Dispatcher->>Kafka: publish (key=orderId)
        alt ack
            Kafka-->>Dispatcher: ok
            Dispatcher->>Outbox: status=SENT
        else ошибка сериализации
            Dispatcher->>Outbox: status=POISON
            Dispatcher->>Dispatcher: алерт, без retry
        else transient error
            Dispatcher->>Dispatcher: retry §3.6
            alt retry исчерпан
                Dispatcher->>Outbox: status=FAILED
                Dispatcher->>Dispatcher: алерт + quarantine runbook
            end
        end
    end

5. Связанные артефакты

6. Связи с другими разделами базы

Теория и контекст — без повторения артефактов из §5:

• Асинхронные брокеры и гарантии доставки — 03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events)
• Event-Driven Architecture и transactional outbox — 03.05.06 Event-Driven Architecture
• Безопасность канала (TLS, SASL, ACL) — 03.05.05 Безопасность API
• Версионирование контрактов и breaking changes — 03.05.07 Управление версионированием API и жизненным циклом
• Декомпозиция producer / dispatcher / outbox — 03.01.03 Декомпозиция системы на подсистемы и модули

7. Источники и дополнительные материалы

Книги и стандарты

• JSON Schema Draft 07 — https://json-schema.org/draft-07/json-schema-release-notes.html
• AsyncAPI Specification — https://www.asyncapi.com/docs/reference/specification/latest

Документация и практики

• Apache Kafka Documentation — Producer API — https://kafka.apache.org/documentation/#producerapi
• Confluent Schema Registry — https://docs.confluent.io/platform/current/schema-registry/index.html
• RabbitMQ Documentation: Publisher Confirms — https://www.rabbitmq.com/docs/confirms
• Designing Event-Driven Systems (Ben Stopford) — https://www.confluent.io/designing-event-driven-systems/
• Microservices Patterns: Transactional Outbox (Chris Richardson) — https://microservices.io/patterns/data/transactional-outbox.html