Producer на Go: публикуем события в Kafka (franz-go)
Producer на Go: публикуем события в Kafka (franz-go)
franz-go - современная Go-библиотека для Kafka. Написана с нуля в 2021, поддерживает все Kafka API начиная с версии 0.8, активно развивается. В отличие от sarama, у неё понятный API и нет накопленного технического долга.
go get github.com/twmb/franz-go/pkg/kgo
Создание клиента
package main
import (
"context"
"fmt"
"log"
"github.com/twmb/franz-go/pkg/kgo"
)
func main() {
client, err := kgo.NewClient(
kgo.SeedBrokers("localhost:9092"),
kgo.DefaultProduceTopic("lesson-events"),
)
if err != nil {
log.Fatal(err)
}
defer client.Close()
}
SeedBrokers - bootstrap-серверы. Клиент подключится к ним, получит метаданные кластера (список всех брокеров, топиков, партиций) и дальше работает самостоятельно.
Синхронная отправка
record := &kgo.Record{
Topic: "lesson-events",
Key: []byte("user-42"), // partition key
Value: []byte(`{"event":"lesson.completed","lessonId":"go-01"}`),
Headers: []kgo.RecordHeader{
{Key: "content-type", Value: []byte("application/json")},
{Key: "version", Value: []byte("1")},
},
}
results := client.ProduceSync(ctx, record)
if err := results.FirstErr(); err != nil {
return fmt.Errorf("produce: %w", err)
}
ProduceSync блокирует до получения подтверждения от брокера. Удобно для простых случаев, но медленно при высоком throughput - каждая отправка ждёт ack.
Асинхронная отправка
var wg sync.WaitGroup
for _, event := range events {
wg.Add(1)
record := &kgo.Record{
Topic: "lesson-events",
Key: []byte(event.UserID),
Value: marshal(event),
}
client.Produce(ctx, record, func(r *kgo.Record, err error) {
defer wg.Done()
if err != nil {
log.Printf("produce error: %v", err)
}
})
}
wg.Wait()
Produce (без Sync) принимает callback и возвращает сразу. Клиент буферизует записи и отправляет батчами - это даёт на порядок больший throughput.
Partition Key и порядок
// Все события одного пользователя идут в одну партицию
record := &kgo.Record{
Key: []byte(userID), // partition key
Value: payload,
}
franz-go хеширует Key (murmur2, как Java-клиент) и выбирает партицию. Одинаковый ключ = одна и та же партиция = порядок гарантирован. Это критично, если нужна последовательность событий: lesson.started → lesson.completed. Партицию выбирает клиент, а не брокер, поэтому все producer-ы одного топика должны хешировать ключ одинаково (см. раздел про PHP ниже).
Без ключа (nil) franz-go использует sticky-распределение (UniformBytesPartitioner): пишет в одну партицию, пока не накопит батч (около 64 КБ), потом переключается на другую. Это не round-robin: при малом потоке события без ключа подолгу идут в одну партицию. Порядок между партициями не гарантирован.
Производительная конфигурация
client, err := kgo.NewClient(
kgo.SeedBrokers("localhost:9092"),
// Батчинг: ждать до 20ms, чтобы накопить батч (по умолчанию 10ms)
kgo.ProducerLinger(20 * time.Millisecond),
// Максимальный размер батча
kgo.ProducerBatchMaxBytes(1_000_000), // 1MB
// Сжатие (snappy - хороший баланс CPU vs compression ratio)
kgo.ProducerBatchCompression(kgo.SnappyCompression()),
// Требуем подтверждения от всех in-sync реплик (ISR - реплики,
// не отстающие от лидера; подробнее - урок о гарантиях доставки)
kgo.RequiredAcks(kgo.AllISRAcks()),
// Таймаут на доставку записи
kgo.RecordDeliveryTimeout(10 * time.Second),
)
ProducerLinger - ключевой параметр для баланса задержки и throughput: сколько клиент ждёт, чтобы накопить батч для партиции. С franz-go v1.20 по умолчанию это 10ms (раньше было 0). ProduceSync сам снимает ожидание для своих партиций, так что синхронная отправка не ждёт linger. Для минимальной задержки ставят ProducerLinger(0), для большего throughput значение увеличивают.
Graceful Shutdown
func runProducer(ctx context.Context) error {
client, err := kgo.NewClient(kgo.SeedBrokers("localhost:9092"))
if err != nil {
return err
}
defer func() {
// ctx к этому моменту обычно уже отменён сигналом остановки, и
// Flush(ctx) вернулся бы сразу, ничего не отправив. Даём Flush
// свой контекст: не отменяемый сигналом, но с таймаутом.
flushCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 10*time.Second)
defer cancel()
// Flush ждёт, пока все буферизованные записи будут отправлены
if err := client.Flush(flushCtx); err != nil {
log.Printf("flush error: %v", err)
}
client.Close()
}()
// ... produce events ...
return nil
}
client.Close() без Flush теряет записи из буфера: franz-go завершает их с ошибкой ErrClientClosed. Всегда вызывай Flush перед Close, и со своим контекстом с таймаутом, а не с уже отменённым. В HTTP-сервере вызывай Flush в shutdown hook.
Producer как зависимость (Clean Architecture)
// domain/events.go
type LessonCompletedEvent struct {
UserID string
LessonID string
At time.Time
}
// adapters/kafka_publisher.go
type KafkaPublisher struct {
client *kgo.Client
topic string
}
func NewKafkaPublisher(brokers []string, topic string) (*KafkaPublisher, error) {
client, err := kgo.NewClient(
kgo.SeedBrokers(brokers...),
kgo.ProducerLinger(20*time.Millisecond),
kgo.RequiredAcks(kgo.AllISRAcks()),
)
if err != nil {
return nil, err
}
return &KafkaPublisher{client: client, topic: topic}, nil
}
func (p *KafkaPublisher) PublishLessonCompleted(ctx context.Context, e LessonCompletedEvent) error {
payload, _ := json.Marshal(e)
r := &kgo.Record{
Topic: p.topic,
Key: []byte(e.UserID),
Value: payload,
}
return p.client.ProduceSync(ctx, r).FirstErr()
}
func (p *KafkaPublisher) Close(ctx context.Context) error {
if err := p.client.Flush(ctx); err != nil {
return err
}
p.client.Close()
return nil
}
Use case работает с интерфейсом EventPublisher, не зная о Kafka - принцип инверсии зависимостей.
Обработка ошибок
results := client.ProduceSync(ctx, record)
for _, result := range results {
if result.Err != nil {
// Retryable: network error, leader election
// Non-retryable: message too large, topic not found
// RecordDeliveryTimeout franz-go сообщает своей ошибкой ErrRecordTimeout,
// а DeadlineExceeded придёт, если истёк сам ctx
if errors.Is(result.Err, kgo.ErrRecordTimeout) || errors.Is(result.Err, context.DeadlineExceeded) {
// таймаут - попробовать позже
} else {
log.Printf("permanent error for record: %v", result.Err)
}
}
}
franz-go автоматически ретраит транзиентные ошибки (leader election, временная недоступность брокера). RecordDeliveryTimeout ограничивает суммарное время всех попыток.
PHP: публикация через rdkafka
<?php
$conf = new RdKafka\Conf();
$conf->set('metadata.broker.list', 'localhost:9092');
$conf->set('socket.timeout.ms', '3000');
// Тот же хеш ключа, что у franz-go и Java-клиента. По умолчанию librdkafka
// использует consistent_random (CRC32), и один ключ из PHP и из Go
// попал бы в разные партиции.
$conf->set('partitioner', 'murmur2_random');
$producer = new RdKafka\Producer($conf);
$topic = $producer->newTopic('lesson-events');
$payload = json_encode(['event' => 'lesson.completed', 'lessonId' => 'go-01']);
$topic->produce(RD_KAFKA_PARTITION_UA, 0, $payload, $userID); // ключ = $userID
$producer->flush(3000); // ждём подтверждения
RD_KAFKA_PARTITION_UA - unassigned: партицию по ключу выберет partitioner librdkafka на стороне клиента, а не брокер. Поэтому настройка partitioner важна: без murmur2_random порядок событий одного пользователя, отправленных из PHP и из Go, не гарантирован.
Типичные ошибки
Не вызывать Flush при завершении - последние N записей из буфера теряются при остановке сервиса. Особенно заметно с ProducerLinger: буфер копит события до 10-20ms, а потом сервис останавливается.
RequiredAcks(kgo.NoAck()) - отправка без подтверждения. Максимальный throughput, нулевая надёжность. Для продакшна минимум kgo.LeaderAck(), лучше kgo.AllISRAcks().
Один client на весь процесс - это правильно. Создавать новый client на каждый запрос - дорого (TCP handshake, получение метаданных). kgo.Client потокобезопасен.
Смотри также
- Message Brokers - Consumer Group - как читать то, что отправил producer
- Message Brokers - Exactly-once - idempotent producer и транзакции
- Event-Driven - Гарантии доставки - теория at-least-once и exactly-once
Мини-задание
- Подними Kafka из предыдущего урока, напиши
main.goсKafkaPublisherи отправь 5 событий - Проверь через
kafka-console-consumer --from-beginningчто все 5 дошли - Отправь 10 000 событий асинхронным
ProduceсProducerLinger(0)и сProducerLinger(20ms)- сравни общее время и число батчей (подсказка: приProduceSyncпо одной записи разницы не будет, он снимает linger сам) - Попробуй отправить запись размером 2MB (больше
ProducerBatchMaxBytes) - что вернётProduceSync? - Реализуй
Close(ctx)сFlushи добавь его вhttp.Server.RegisterOnShutdown