Producer на Go: публикуем события в RabbitMQ

Producer (publisher) отправляет события в exchange. Его задача - надёжно доставить сообщение брокеру. Бизнес-правила остаются в домене, publisher - чистый транспорт (см. также event-driven pub/sub).

Структура события

Хорошее событие содержит всё, что нужно потребителю, и не заставляет его ходить в другие сервисы:

type LessonCompletedEvent struct {
    EventID     string    `json:"event_id"`
    Type        string    `json:"type"`
    UserID      int64     `json:"user_id"`
    LessonID    int64     `json:"lesson_id"`
    TrackID     int64     `json:"track_id"`
    CompletedAt time.Time `json:"completed_at"`
    Version     int       `json:"version"`
}

// MessageID отдаёт EventID для свойства MessageId в AMQP (см. Publisher ниже).
func (e LessonCompletedEvent) MessageID() string { return e.EventID }
<?php
declare(strict_types=1);

final readonly class LessonCompletedEvent
{
    public function __construct(
        public string $eventId,
        public string $type,
        public int $userId,
        public int $lessonId,
        public int $trackId,
        public DateTimeImmutable $completedAt,
        public int $version,
    ) {}
}
from dataclasses import dataclass
from datetime import datetime
from typing import Any


@dataclass(frozen=True, slots=True)
class LessonCompletedEvent:
    event_id: str
    event_type: str  # на проводе остаётся "type" - см. to_dict
    user_id: int
    lesson_id: int
    track_id: int
    completed_at: datetime
    version: int

    # Аналог json-тегов: ключи JSON-схемы события, а не имена полей класса
    def to_dict(self) -> dict[str, Any]:
        return {
            "event_id": self.event_id,
            "type": self.event_type,
            "user_id": self.user_id,
            "lesson_id": self.lesson_id,
            "track_id": self.track_id,
            "completed_at": self.completed_at.isoformat(),
            "version": self.version,
        }
Поле          Зачем
────────      ──────────────────────────────────────
event_id      Уникальный ID для идемпотентности и трейсинга
type          Тип события - consumer решает, обрабатывать или нет
version       Версия схемы - для обратной совместимости
*_id поля     Данные события - consumer не должен ходить в БД

ℹ️ Генерация EventID

UUID v4 - надёжный выбор. Вариант с time.Now().UnixNano() подходит для прототипов, но в продакшене при высокой нагрузке может дать коллизии. Используй github.com/google/uuid.

Простой Publisher

import amqp "github.com/rabbitmq/amqp091-go"

type RabbitPublisher struct {
    ch       *amqp.Channel
    exchange string
}

func NewRabbitPublisher(ch *amqp.Channel, exchange string) *RabbitPublisher {
    return &RabbitPublisher{ch: ch, exchange: exchange}
}

// messageID берёт ID из самого события, если он есть: тогда повторная
// отправка того же события уйдёт с тем же MessageId, и consumer сможет
// сопоставить логи и отбросить дубль.
func messageID(event any) string {
    if e, ok := event.(interface{ MessageID() string }); ok && e.MessageID() != "" {
        return e.MessageID()
    }
    return uuid.New().String()
}

func (p *RabbitPublisher) Publish(ctx context.Context, routingKey string, event any) error {
    body, err := json.Marshal(event)
    if err != nil {
        return fmt.Errorf("marshal event: %w", err)
    }

    return p.ch.PublishWithContext(ctx,
        p.exchange,  // exchange
        routingKey,  // routing key
        false,       // mandatory
        false,       // immediate
        amqp.Publishing{
            ContentType:  "application/json",
            DeliveryMode: amqp.Persistent,  // сообщение переживёт рестарт
            MessageId:    messageID(event),
            Timestamp:    time.Now(),
            Body:         body,
        },
    )
}
<?php
declare(strict_types=1);

use PhpAmqpLib\Channel\AMQPChannel;
use PhpAmqpLib\Message\AMQPMessage;
use Symfony\Component\Uid\Uuid;

final class RabbitPublisher
{
    public function __construct(
        private readonly AMQPChannel $ch,
        private readonly string $exchange,
    ) {}

    public function publish(string $routingKey, object $event): void
    {
        $body = json_encode($event, JSON_THROW_ON_ERROR);

        $msg = new AMQPMessage($body, [
            'content_type'  => 'application/json',
            'delivery_mode' => AMQPMessage::DELIVERY_MODE_PERSISTENT, // переживёт рестарт
            // ID события, если он есть: ретраи одного события уйдут с одним message_id
            'message_id'    => $event->eventId ?? Uuid::v4()->toRfc4122(),
            'timestamp'     => time(),
        ]);

        $this->ch->basic_publish($msg, $this->exchange, $routingKey);
    }
}

В Symfony Messenger обычно не пишут publisher руками - MessageBusInterface::dispatch($event) + AmqpTransport сделают всё то же самое плюс middleware-стек.

import json
import time
import uuid
from typing import Any, Protocol

import pika
from pika.adapters.blocking_connection import BlockingChannel


class Event(Protocol):
    def to_dict(self) -> dict[str, Any]: ...


class RabbitPublisher:
    def __init__(self, ch: BlockingChannel, exchange: str) -> None:
        self._ch = ch
        self._exchange = exchange

    # Контекста с отменой, как в Go, у BlockingConnection нет: таймауты
    # задаются при подключении (socket_timeout, blocked_connection_timeout).
    def publish(self, routing_key: str, event: Event) -> None:
        # Несериализуемое поле - TypeError из json.dumps, аналог ошибки marshal
        body = json.dumps(event.to_dict()).encode()

        self._ch.basic_publish(
            exchange=self._exchange,
            routing_key=routing_key,
            body=body,
            mandatory=False,
            properties=pika.BasicProperties(
                content_type="application/json",
                delivery_mode=pika.DeliveryMode.Persistent,  # сообщение переживёт рестарт
                # ID события, если он есть: ретраи одного события - один message_id
                message_id=getattr(event, "event_id", None) or str(uuid.uuid4()),
                timestamp=int(time.time()),
            ),
        )

Persistent Messages

В classic-очереди сообщение с DeliveryMode 1 (transient) живёт в памяти и не переживёт рестарт RabbitMQ.

DeliveryMode: 1 (Transient)    Быстро, но ненадёжно
DeliveryMode: 2 (Persistent)   Медленнее, но сообщение на диске
// Persistent + durable queue = сообщение переживёт рестарт
amqp.Publishing{
    DeliveryMode: amqp.Persistent,  // = 2
    // ...
}

ℹ️ Quorum-очереди: надёжный вариант в RabbitMQ 4.x

Кроме classic-очередей есть quorum-очереди (x-queue-type: quorum в аргументах QueueDeclare). Они всегда пишут сообщения на диск, независимо от DeliveryMode, и реплицируют их на несколько узлов кластера. Для надёжных очередей в RabbitMQ 4.x рекомендуют именно их: зеркалирование classic-очередей (mirrored queues) в 4.0 удалено. В примерах трека для простоты используются classic-очереди на одном узле.

⚠️ Persistent ≠ гарантия доставки

Persistent гарантирует запись на диск на стороне брокера. Но между Publish() и записью на диск может произойти сбой. Чтобы знать, что брокер принял сообщение, нужен Publisher Confirm.

Но и confirm - не всё. При mandatory=false (как во всех примерах урока) сообщение, которое не попало ни в одну очередь (опечатка в routing key, нет binding), брокер молча выбросит и всё равно пришлёт ack. Чтобы узнать о таком случае, публикуют с mandatory=true и слушают возвраты через ch.NotifyReturn.

Publisher Confirms

Publisher Confirm - механизм, когда RabbitMQ подтверждает, что взял ответственность за сообщение (для persistent-сообщения в durable-очереди - после записи на диск):

func NewConfirmedPublisher(ch *amqp.Channel, exchange string) (*RabbitPublisher, error) {
    // Включаем режим подтверждений
    if err := ch.Confirm(false); err != nil {
        return nil, fmt.Errorf("enable confirms: %w", err)
    }
    return &RabbitPublisher{ch: ch, exchange: exchange}, nil
}

func (p *RabbitPublisher) PublishWithConfirm(ctx context.Context, routingKey string, event any) error {
    body, err := json.Marshal(event)
    if err != nil {
        return fmt.Errorf("marshal: %w", err)
    }

    // Получаем канал подтверждений
    confirmation, err := p.ch.PublishWithDeferredConfirmWithContext(ctx,
        p.exchange,
        routingKey,
        false,
        false,
        amqp.Publishing{
            ContentType:  "application/json",
            DeliveryMode: amqp.Persistent,
            MessageId:    messageID(event),
            Body:         body,
        },
    )
    if err != nil {
        return fmt.Errorf("publish: %w", err)
    }

    // Ждём подтверждения от брокера
    ok, err := confirmation.WaitContext(ctx)
    if err != nil {
        return fmt.Errorf("wait confirm: %w", err)
    }
    if !ok {
        return fmt.Errorf("message nacked by broker")
    }

    return nil
}
<?php
declare(strict_types=1);

use PhpAmqpLib\Channel\AMQPChannel;
use PhpAmqpLib\Message\AMQPMessage;
use Symfony\Component\Uid\Uuid;

final class ConfirmedRabbitPublisher
{
    private bool $lastAcked = false;

    public function __construct(
        private readonly AMQPChannel $ch,
        private readonly string $exchange,
    ) {
        // Включаем режим подтверждений
        $this->ch->confirm_select();
        $this->ch->set_ack_handler(function (): void { $this->lastAcked = true; });
        $this->ch->set_nack_handler(function (): void { $this->lastAcked = false; });
    }

    public function publish(string $routingKey, object $event): void
    {
        $body = json_encode($event, JSON_THROW_ON_ERROR);

        $msg = new AMQPMessage($body, [
            'content_type'  => 'application/json',
            'delivery_mode' => AMQPMessage::DELIVERY_MODE_PERSISTENT,
            'message_id'    => $event->eventId ?? Uuid::v4()->toRfc4122(),
        ]);

        $this->lastAcked = false;
        $this->ch->basic_publish($msg, $this->exchange, $routingKey);

        // Ждём подтверждения от брокера
        $this->ch->wait_for_pending_acks(timeout: 5.0);

        if (!$this->lastAcked) {
            throw new RuntimeException('message nacked by broker');
        }
    }
}
import json
import uuid

import pika
from pika.adapters.blocking_connection import BlockingChannel
from pika.exceptions import NackError


class PublishNackedError(Exception):
    """Брокер не подтвердил приём сообщения (nack)."""


class ConfirmedRabbitPublisher(RabbitPublisher):
    def __init__(self, ch: BlockingChannel, exchange: str) -> None:
        # Включаем режим подтверждений
        ch.confirm_delivery()
        super().__init__(ch, exchange)

    def publish_with_confirm(self, routing_key: str, event: Event) -> None:
        body = json.dumps(event.to_dict()).encode()

        # После confirm_delivery basic_publish сам блокируется до ответа брокера:
        # отдельного шага «ждём подтверждение» нет, а nack приходит исключением.
        try:
            self._ch.basic_publish(
                exchange=self._exchange,
                routing_key=routing_key,
                body=body,
                properties=pika.BasicProperties(
                    content_type="application/json",
                    delivery_mode=pika.DeliveryMode.Persistent,
                    message_id=getattr(event, "event_id", None) or str(uuid.uuid4()),
                ),
            )
        except NackError as e:
            # Граница адаптера: исключение pika переводим в своё, чтобы
            # приложение не импортировало pika. `from e` - не аналог errors.Is:
            # ловят по типу нового исключения, NackError остаётся в __cause__
            raise PublishNackedError("message nacked by broker") from e

Routing Keys: конвенции именования

Хорошие routing key'и - иерархические и предсказуемые:

Паттерн: <domain>.<action>

lesson.completed     ✓  Понятно: урок завершён
lesson.started       ✓  Понятно: урок начат
user.registered      ✓  Понятно: пользователь зарегистрировался

update              ✗  Что обновилось?
event_1             ✗  Бессмысленно
lesson-completed    ✗  Точка, не дефис (topic exchange парсит по точкам)

Сериализация: JSON vs Protobuf

JSON                                 Protobuf
─────────────────────                ─────────────────────
Читаем глазами                       Нужен .proto файл
Гибкий, не требует схемы             Строгая типизация
Медленнее сериализация               Быстрее в 5-10 раз
Больше размер                        Компактнее в 3-5 раз
Хорош для старта                     Хорош для высоких нагрузок

Для большинства проектов JSON - достаточно. Переходи на Protobuf, когда размер сообщений или скорость сериализации станут узким местом. Что бы ты ни выбрал, формат должен совпадать на другом конце: consumer разбирает то же тело и тот же ContentType, и на неизвестной схеме должен уходить в DLQ, а не молча делать ack.

Интеграция с Use Case

Publisher вызывается из use case, но сам не содержит бизнес-логики:

type CompleteLessonUseCase struct {
    progressRepo ProgressRepo
    lessonRepo   LessonRepo
    publisher    EventPublisher
}

func (uc *CompleteLessonUseCase) Execute(ctx context.Context, userID, lessonID int64) error {
    lesson, err := uc.lessonRepo.GetByID(ctx, lessonID)
    if err != nil {
        return err
    }

    // Бизнес-правила - в use case
    if err := uc.progressRepo.MarkCompleted(ctx, userID, lessonID); err != nil {
        return err
    }

    // Publisher - чистый транспорт
    return uc.publisher.Publish(ctx, "lesson.completed", LessonCompletedEvent{
        EventID:     uuid.New().String(),
        Type:        "lesson.completed",
        UserID:      userID,
        LessonID:    lessonID,
        TrackID:     lesson.TrackID,
        CompletedAt: time.Now(),
        Version:     1,
    })
}
<?php
declare(strict_types=1);

use Symfony\Component\Uid\Uuid;

final class CompleteLessonUseCase
{
    public function __construct(
        private readonly ProgressRepository $progressRepo,
        private readonly LessonRepository $lessonRepo,
        private readonly EventPublisher $publisher,
    ) {}

    public function execute(int $userId, int $lessonId): void
    {
        $lesson = $this->lessonRepo->getById($lessonId)
            ?? throw new LessonNotFoundException($lessonId);

        // Бизнес-правила - в use case
        $this->progressRepo->markCompleted($userId, $lessonId);

        // Publisher - чистый транспорт
        $this->publisher->publish('lesson.completed', new LessonCompletedEvent(
            eventId: Uuid::v4()->toRfc4122(),
            type: 'lesson.completed',
            userId: $userId,
            lessonId: $lessonId,
            trackId: $lesson->trackId,
            completedAt: new DateTimeImmutable(),
            version: 1,
        ));
    }
}
import uuid
from datetime import datetime, timezone


class CompleteLessonUseCase:
    def __init__(
        self,
        progress_repo: ProgressRepo,
        lesson_repo: LessonRepo,
        publisher: EventPublisher,
    ) -> None:
        self._progress_repo = progress_repo
        self._lesson_repo = lesson_repo
        self._publisher = publisher

    def execute(self, user_id: int, lesson_id: int) -> None:
        # Нет урока - get_by_id бросит исключение, оно уйдёт выше как return err
        lesson = self._lesson_repo.get_by_id(lesson_id)

        # Бизнес-правила - в use case
        self._progress_repo.mark_completed(user_id, lesson_id)

        # Publisher - чистый транспорт
        self._publisher.publish("lesson.completed", LessonCompletedEvent(
            event_id=str(uuid.uuid4()),
            event_type="lesson.completed",
            user_id=user_id,
            lesson_id=lesson_id,
            track_id=lesson.track_id,
            completed_at=datetime.now(timezone.utc),
            version=1,
        ))

Обработка ошибок публикации

Что делать, если Publish() вернул ошибку?

Стратегия         Когда использовать
────────────      ──────────────────────────────────
Retry             Временная ошибка сети - повтори с backoff.
                  Если канал или соединение закрыты, сначала
                  переоткрой их: закрытый канал сам не оживёт
Outbox            Нужна атомарность: событие пишется в ту же транзакцию
Log + alert       Некритичное событие (аналитика) - залогируй и иди дальше

Подробнее про Outbox - в уроке outbox/inbox. Retry с экспоненциальным backoff:

func (p *RabbitPublisher) PublishWithRetry(ctx context.Context, key string, event any, maxRetries int) error {
    var lastErr error
    for attempt := 0; attempt <= maxRetries; attempt++ {
        err := p.Publish(ctx, key, event)
        if err == nil {
            return nil
        }
        // amqp091-go не восстанавливает закрытый канал: повтор в тот же
        // p.ch будет сразу возвращать ErrClosed. Отдаём ошибку наверх -
        // там переоткроют соединение (conn.Channel()) или запишут в outbox.
        if errors.Is(err, amqp.ErrClosed) {
            return fmt.Errorf("channel closed: %w", err)
        }
        lastErr = err
        backoff := time.Duration(1<<attempt) * 100 * time.Millisecond // 100ms, 200ms, 400ms...
        select {
        case <-ctx.Done(): // сервис останавливается - не ждём backoff
            return ctx.Err()
        case <-time.After(backoff):
        }
    }
    return fmt.Errorf("publish failed after %d retries: %w", maxRetries, lastErr)
}
<?php
declare(strict_types=1);

final class RetryingPublisher
{
    public function __construct(
        private readonly RabbitPublisher $inner,
    ) {}

    public function publishWithRetry(string $routingKey, object $event, int $maxRetries): void
    {
        $lastError = null;
        for ($attempt = 0; $attempt <= $maxRetries; $attempt++) {
            try {
                $this->inner->publish($routingKey, $event);
                return;
            } catch (Throwable $e) {
                $lastError = $e;
                $backoffMs = (1 << $attempt) * 100; // 100ms, 200ms, 400ms...
                usleep($backoffMs * 1000);
            }
        }
        throw new RuntimeException(
            "publish failed after $maxRetries retries: " . $lastError?->getMessage(),
            previous: $lastError,
        );
    }
}

В Symfony Messenger retry_strategy (max_retries, multiplier в messenger.yaml) управляет повторной обработкой сообщения worker-ом, а после исчерпания попыток worker сам перекладывает сообщение в failure_transport. Ошибку отправки в брокер при dispatch() это не покрывает: для неё нужен outbox или собственный ретрай, как выше.

import time


class PublishFailedError(Exception):
    """Публикация не удалась после всех повторов."""


class RabbitPublisher:  # продолжение класса из блока «Простой Publisher»
    def publish_with_retry(self, key: str, event: Event, max_retries: int) -> None:
        last_err: Exception | None = None
        for attempt in range(max_retries + 1):
            try:
                self.publish(key, event)
                return
            except Exception as e:
                last_err = e
                backoff = (1 << attempt) * 0.1  # 100ms, 200ms, 400ms...
                time.sleep(backoff)
        # Своё исключение вместо RuntimeError: вызывающий решает по типу
        # (except PublishFailedError -> outbox/алерт), последнее исключение - в __cause__
        raise PublishFailedError(
            f"publish failed after {max_retries} retries: {last_err}"
        ) from last_err

Мини-задание

  • Напиши RabbitPublisher с методом Publish(ctx, routingKey, event) используя amqp091-go
  • Добавь DeliveryMode: amqp.Persistent и ContentType: "application/json"
  • Опубликуй тестовое событие lesson.completed и проверь в Management UI, что оно попало в нужную очередь
  • Добавь Publisher Confirm и убедись, что брокер подтвердил приём

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.