Мини-проект: LessonCompleted в RabbitMQ и Kafka
Мини-проект: LessonCompleted в RabbitMQ и Kafka
Финальный проект трека. Берём одно событие lesson.completed и доставляем его в два брокера одновременно: в RabbitMQ идёт задача на email-нотификацию, в Kafka - событие для аналитики.
Архитектура
HTTP POST /lessons/{id}/complete
│
▼
CompleteLesson (use case)
│
├── ProgressRepository.MarkCompleted(tx)
├── OutboxRepository.Save(tx, RabbitMQ task) ─────► RabbitMQ
│ │
│ ▼
│ email-worker
│
└── KafkaPublisher.Publish(ctx, event) ──────────► Kafka
│
▼
analytics-consumer
Два брокера - два разных паттерна (почему очередь и лог решают разные задачи - в сравнении RabbitMQ и Kafka):
- RabbitMQ через Outbox: событие пишется атомарно с транзакцией БД; доставка остаётся at-least-once, поэтому воркер писем идемпотентен
- Kafka напрямую после
COMMIT: это dual write из урока про outbox. Если процесс упадёт междуCOMMITи публикацией или Kafka будет недоступна дольшеRecordDeliveryTimeout, событие для аналитики потеряется (at-most-once). Для аналитики это осознанный компромисс ради простоты; если потери недопустимы, пиши и Kafka-событие через outbox, как в уроке 11. Дубли тоже возможны (ретраи producer-а), поэтому consumer аналитики всё равно идемпотентен
Структура проекта
lesson-completed/
├── cmd/
│ ├── api/main.go - HTTP API
│ ├── email-worker/main.go - RabbitMQ consumer
│ └── analytics/main.go - Kafka consumer group
├── domain/
│ └── events.go - LessonCompletedEvent
├── usecases/
│ └── complete_lesson.go - бизнес-логика
├── adapters/
│ ├── rabbitmq_publisher.go - Outbox Poller → RabbitMQ
│ ├── kafka_publisher.go - franz-go producer
│ └── postgres_repo.go - outbox + progress repo
├── docker-compose.yml
└── Makefile
domain/events.go
package domain
import (
"context"
"time"
)
type LessonCompletedEvent struct {
EventID string `json:"eventId"`
UserID string `json:"userId"`
LessonID string `json:"lessonId"`
At time.Time `json:"at"`
}
type EventPublisher interface {
PublishLessonCompleted(ctx context.Context, e LessonCompletedEvent) error
}
usecases/complete_lesson.go
package usecases
import (
"context"
"database/sql"
"encoding/json"
"log"
"time"
"github.com/google/uuid"
"lesson-completed/internal/domain"
)
type CompleteLessonUseCase struct {
progress ProgressRepository
outbox OutboxRepository
kafka EventPublisher
db *sql.DB
}
func (uc *CompleteLessonUseCase) Execute(ctx context.Context, userID, lessonID string) error {
event := domain.LessonCompletedEvent{
EventID: uuid.New().String(),
UserID: userID,
LessonID: lessonID,
At: time.Now().UTC(),
}
// 1. Transactionally save progress + RabbitMQ task to outbox
err := withTx(ctx, uc.db, func(tx *sql.Tx) error {
if err := uc.progress.MarkCompleted(ctx, tx, userID, lessonID); err != nil {
return err
}
payload, _ := json.Marshal(event)
return uc.outbox.Save(ctx, tx, OutboxEntry{
Topic: "notifications",
RoutingKey: "lesson.completed",
PartitionKey: userID,
Payload: payload,
EventID: event.EventID,
})
})
if err != nil {
return err
}
// 2. Публикация в Kafka после COMMIT - вне транзакции и без outbox.
// Упадёт процесс здесь или Kafka недоступна дольше RecordDeliveryTimeout -
// событие для аналитики потеряно (at-most-once). Осознанный компромисс.
if err := uc.kafka.PublishLessonCompleted(ctx, event); err != nil {
// Урок уже зачтён - ошибку пользователю не возвращаем, но громко логируем
// (и считаем метрикой: см. урок про мониторинг Kafka)
log.Printf("analytics event %s not published: %v", event.EventID, err)
}
return nil
}
adapters/kafka_publisher.go
package adapters
import (
"context"
"encoding/json"
"time"
"github.com/twmb/franz-go/pkg/kgo"
"lesson-completed/internal/domain"
)
type KafkaPublisher struct {
client *kgo.Client
topic string
}
func NewKafkaPublisher(brokers []string, topic string) (*KafkaPublisher, error) {
client, err := kgo.NewClient(
kgo.SeedBrokers(brokers...),
kgo.RequiredAcks(kgo.AllISRAcks()),
kgo.ProducerLinger(5*time.Millisecond),
)
if err != nil {
return nil, err
}
return &KafkaPublisher{client: client, topic: topic}, nil
}
func (p *KafkaPublisher) PublishLessonCompleted(ctx context.Context, e domain.LessonCompletedEvent) error {
payload, _ := json.Marshal(e)
r := &kgo.Record{
Topic: p.topic,
Key: []byte(e.UserID),
Value: payload,
Headers: []kgo.RecordHeader{
{Key: "id", Value: []byte(e.EventID)}, // как в уроке про Kafka outbox
},
}
return p.client.ProduceSync(ctx, r).FirstErr()
}
cmd/email-worker/main.go
Топология - схема retry из урока про DLQ: отказ уходит через DLX в retry.email, отлёживается 30 секунд и возвращается только в email-notifications; после трёх попыток - в финальную dlq.email. Exchange notifications - тот, в который публикует outbox poller (Topic: "notifications" в use case).
func main() {
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()
db, err := sql.Open("pgx", os.Getenv("DB_URL")) // inbox для дедупликации
must(err)
defer db.Close()
conn, err := amqp091.Dial(os.Getenv("RABBITMQ_URL"))
must(err)
defer conn.Close()
ch, err := conn.Channel()
must(err)
pubCh, err := conn.Channel() // отдельный канал для публикации в DLQ с confirm
must(err)
must(pubCh.Confirm(false))
// Объявления идемпотентны: poller и worker могут объявлять одно и то же
must(ch.ExchangeDeclare("notifications", "topic", true, false, false, false, nil))
_, err = ch.QueueDeclare("retry.email", true, false, false, false, amqp091.Table{
"x-dead-letter-exchange": "",
"x-dead-letter-routing-key": "email-notifications",
"x-message-ttl": int32(30000),
})
must(err)
_, err = ch.QueueDeclare("email-notifications", true, false, false, false, amqp091.Table{
"x-dead-letter-exchange": "",
"x-dead-letter-routing-key": "retry.email",
})
must(err)
_, err = ch.QueueDeclare("dlq.email", true, false, false, false, nil)
must(err)
must(ch.QueueBind("email-notifications", "lesson.completed", "notifications", false, nil))
must(ch.Qos(10, 0, false)) // prefetch
msgs, err := ch.Consume("email-notifications", "email-worker", false, false, false, false, nil)
must(err)
for {
select {
case <-ctx.Done():
return
case msg, ok := <-msgs:
if !ok {
return
}
err := handle(ctx, db, msg.Body)
switch {
case err == nil:
msg.Ack(false)
case retryCount(msg, "email-notifications", "rejected") >= 3:
// Попытки исчерпаны: копия с причиной в dlq.email, потом ack.
// Если публикация не удалась - не теряем, ещё один круг через retry.
if pErr := publishToDLQ(ctx, pubCh, "dlq.email", msg, err); pErr != nil {
log.Printf("dlq publish failed: %v", pErr)
msg.Nack(false, false)
} else {
msg.Ack(false)
}
default:
log.Printf("send email failed, retry later: %v", err)
msg.Nack(false, false) // без requeue: через DLX в retry.email
}
}
}
}
// handle отмечает событие в inbox и отправляет письмо в одной транзакции:
// повторная доставка того же eventId письма не отправит.
func handle(ctx context.Context, db *sql.DB, body []byte) error {
var e domain.LessonCompletedEvent
if err := json.Unmarshal(body, &e); err != nil {
return fmt.Errorf("decode: %w", err)
}
if e.EventID == "" {
return errors.New("missing eventId")
}
return withTx(ctx, db, func(tx *sql.Tx) error {
res, err := tx.ExecContext(ctx,
`INSERT INTO inbox (event_id, handler) VALUES ($1, 'email')
ON CONFLICT (event_id, handler) DO NOTHING`, e.EventID)
if err != nil {
return err
}
if n, err := res.RowsAffected(); err != nil || n == 0 {
return err // n == 0: дубль, письмо уже отправляли
}
// Письмо - внешний эффект: если оно ушло, а COMMIT упал, повтор
// отправит его ещё раз. Это окно остаётся; закрыть его может только
// ключ идемпотентности на стороне почтового провайдера.
return sendEmail(ctx, e)
})
}
retryCount и публикация в финальную DLQ с publisher confirm - те же, что retryCount и publishToFinalDLQ в уроке про DLQ.
cmd/analytics/main.go
func main() {
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()
client, err := kgo.NewClient(
kgo.SeedBrokers(os.Getenv("KAFKA_BROKERS")),
kgo.ConsumerGroup("analytics"),
kgo.ConsumeTopics("lesson-events"),
kgo.DisableAutoCommit(),
)
if err != nil {
log.Fatal(err)
}
defer client.Close()
for {
fetches := client.PollFetches(ctx)
if ctx.Err() != nil {
// Записи последнего poll не обработаны - не коммитим их,
// после рестарта группа прочитает их снова
return
}
for _, e := range fetches.Errors() {
log.Printf("fetch error: %s/%d: %v", e.Topic, e.Partition, e.Err)
}
var processed []*kgo.Record
var failed error
fetches.EachPartition(func(p kgo.FetchTopicPartition) {
for _, r := range p.Records {
if failed != nil {
return
}
// recordAnalytics идемпотентен: пропускает уже учтённый id из заголовка
if err := recordAnalytics(r); err != nil {
failed = err
return
}
processed = append(processed, r)
}
})
if len(processed) > 0 {
// Свой контекст: коммит должен пройти и после сигнала остановки
commitCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 10*time.Second)
if err := client.CommitRecords(commitCtx, processed...); err != nil {
log.Printf("commit error: %v", err)
}
cancel()
}
if failed != nil {
// Перешагнуть через упавшую запись нельзя (см. урок про consumer):
// выходим, compose перезапустит сервис, чтение начнётся с коммита
log.Printf("analytics error, restarting: %v", failed)
return
}
}
}
docker-compose.yml
services:
postgres:
image: postgres:16-alpine
environment:
POSTGRES_DB: app
POSTGRES_USER: app
POSTGRES_PASSWORD: secret
ports: ["5432:5432"]
rabbitmq:
image: rabbitmq:4-management
hostname: rabbitmq # фиксированное имя узла - см. урок про RabbitMQ в Compose
ports: ["5672:5672", "15672:15672"]
environment:
RABBITMQ_DEFAULT_USER: guest
RABBITMQ_DEFAULT_PASS: guest
healthcheck:
test: ["CMD", "rabbitmq-diagnostics", "-q", "check_port_connectivity"]
interval: 10s
timeout: 5s
retries: 5
kafka:
image: confluentinc/cp-kafka:8.0.0
hostname: kafka
ports: ["9092:9092"]
environment:
KAFKA_NODE_ID: 1
KAFKA_PROCESS_ROLES: broker,controller
# INTERNAL - для контейнеров (kafka:29092), EXTERNAL - для хоста (localhost:9092)
KAFKA_LISTENERS: INTERNAL://0.0.0.0:29092,EXTERNAL://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka:29092,EXTERNAL://localhost:9092
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT,CONTROLLER:PLAINTEXT
KAFKA_INTER_BROKER_LISTENER_NAME: INTERNAL
KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
CLUSTER_ID: "MkU3OEVBNTcwNTJENDM2Qk"
healthcheck:
test: ["CMD", "kafka-topics", "--bootstrap-server", "localhost:9092", "--list"]
interval: 10s
timeout: 10s
retries: 10
kafka-ui:
image: ghcr.io/kafbat/kafka-ui:v1.4.2
ports: ["8090:8080"] # 8080 занят api
environment:
KAFKA_CLUSTERS_0_NAME: local
KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:29092
depends_on:
kafka: { condition: service_healthy }
api:
build: ./cmd/api
ports: ["8080:8080"]
environment:
DB_URL: postgres://app:secret@postgres:5432/app
RABBITMQ_URL: amqp://guest:guest@rabbitmq:5672/
KAFKA_BROKERS: kafka:29092 # не localhost: api живёт в Docker-сети
depends_on:
postgres: { condition: service_started }
rabbitmq: { condition: service_healthy }
kafka: { condition: service_healthy }
email-worker:
build: ./cmd/email-worker
restart: unless-stopped
environment:
DB_URL: postgres://app:secret@postgres:5432/app # inbox
RABBITMQ_URL: amqp://guest:guest@rabbitmq:5672/
depends_on:
postgres: { condition: service_started }
rabbitmq: { condition: service_healthy }
analytics:
build: ./cmd/analytics
restart: unless-stopped # после ошибки обработки перечитает с коммита
environment:
KAFKA_BROKERS: kafka:29092
depends_on:
kafka: { condition: service_healthy }
Почему kafka:29092, а не kafka:9092: брокер отдаёт клиенту адрес того listener-а, к которому тот подключился. По порту 9092 (EXTERNAL) это localhost:9092, и контейнер стал бы подключаться к самому себе. Подробно - в уроке про Kafka в Compose.
Проверка
# Запуск
docker compose up -d
# Отправить событие
curl -X POST http://localhost:8080/lessons/go-01/complete \
-H "X-User-ID: user-42"
# Проверить RabbitMQ
open http://localhost:15672 # guest/guest
# → Queues → email-notifications → Messages
# Проверить Kafka: kafka-ui на http://localhost:8090 → Topics → lesson-events
# или consumer group из CLI
docker compose exec kafka kafka-consumer-groups \
--bootstrap-server localhost:9092 \
--describe --group analytics
Типичные ошибки
Не закрывать Kafka producer при shutdown - вызывай client.Flush(ctx) перед client.Close() в HTTP-сервере, иначе последние события теряются. Что ничего не потерялось, проще всего проверить по lag consumer group - мониторинг Kafka.
Публиковать в Kafka до фиксации транзакции - если транзакция откатится после Kafka-публикации, event ушёл без бизнес-данных. В этом проекте Kafka публикуется после успешного commit (вызов uc.kafka.PublishLessonCompleted идёт после withTx). Обратная сторона - возможная потеря события при сбое после commit, см. раздел про архитектуру.
Не реализовывать idempotent consumer в analytics - Kafka гарантирует at-least-once, дубли возможны. Analytics consumer должен уметь пропускать уже обработанные eventId. Приёмы - в уроке про идемпотентность, а inbox-таблица под Kafka с транзакцией вокруг проверки и отметки - в Transactional Outbox с Kafka.
Смотри также
- Hex Architecture - Use Cases - EventPublisher как порт
- Event-Driven - Outbox + Inbox - теория паттерна
- Message Brokers - RabbitMQ Producer - детали AMQP publisher
Мини-задание
- Реализуй структуру проекта из урока:
cmd/api,cmd/email-worker,cmd/analytics - Напиши
CompleteLessonuse case с транзакционным outbox для RabbitMQ - Реализуй
KafkaPublisherсAllISRAcksиFlushна shutdown - Подними весь docker-compose, отправь 10 событий, проверь что в RabbitMQ и Kafka всё дошло
- Симулируй сбой: останови email-worker, отправь событие, перезапусти worker - сообщение должно быть в очереди
- Добавь idempotency в analytics consumer: пропускать дубли по заголовку
id(этоeventIdсобытия)