Мини-проект: 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.

Смотри также

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

  • Реализуй структуру проекта из урока: cmd/api, cmd/email-worker, cmd/analytics
  • Напиши CompleteLesson use case с транзакционным outbox для RabbitMQ
  • Реализуй KafkaPublisher с AllISRAcks и Flush на shutdown
  • Подними весь docker-compose, отправь 10 событий, проверь что в RabbitMQ и Kafka всё дошло
  • Симулируй сбой: останови email-worker, отправь событие, перезапусти worker - сообщение должно быть в очереди
  • Добавь idempotency в analytics consumer: пропускать дубли по заголовку id (это eventId события)

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