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 и убедись, что брокер подтвердил приём