Spring Kafka: Producer & Consumer
Giriş
Bir nehri düşünün. Üretici fabrikalar nehre malzeme bırakır (produce), aşağıdaki fabrikalar nehirden malzeme çeker (consume). Nehir her şeyi saklar, asla unutmaz — bir fabrika geçici olarak kapansa bile, açıldığında kaldığı yerden devam edebilir. Kafka tam da böyle bir "nehir"dir: yüksek hacimli, dayanıklı, sıralı bir veri akış platformu.
Spring Boot, Apache Kafka ile entegrasyon için spring-kafka projesini sunar. Bu proje, Kafka'nın Java client'ını Spring ekosistemiyle sorunsuz çalışacak şekilde soyutlar. KafkaTemplate ile mesaj gönderme, @KafkaListener ile mesaj alma, serialization/deserialization yapılandırması, consumer group yönetimi ve hata yönetimini bu derste detaylıca inceleyeceğiz.
Bağımlılık ve Temel Yapılandırma
<dependency>
<groupId>org.springframework.kafka</groupId>
<artifactId>spring-kafka</artifactId>
</dependency>spring:
kafka:
bootstrap-servers: localhost:9092
producer:
key-serializer: org.apache.kafka.common.serialization.StringSerializer
value-serializer: org.springframework.kafka.support.serializer.JsonSerializer
acks: all # Tüm replica'lar onaylasın
retries: 3 # Hata durumunda 3 deneme
properties:
enable.idempotence: true # Exactly-once producer (duplicate engelleme)
max.in.flight.requests.per.connection: 5
compression.type: snappy # Mesaj sıkıştırma
linger.ms: 20 # 20ms buffer (batch gönderim)
batch.size: 32768 # 32 KB batch boyutu
consumer:
group-id: order-service
auto-offset-reset: earliest # Yeni consumer en baştan okusun
key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
value-deserializer: org.springframework.kafka.support.serializer.JsonDeserializer
properties:
spring.json.trusted.packages: "com.example.events,com.example.dto"
spring.json.use.type.headers: true
max.poll.records: 100 # Bir poll'da maksimum 100 kayıt
max.poll.interval.ms: 300000 # 5 dakika poll aralığı
enable-auto-commit: false # Manuel offset commit (önerilen)
listener:
ack-mode: manual_immediate # Manuel acknowledgement
concurrency: 3 # 3 consumer thread (partition sayısına göre)KafkaTemplate ile Mesaj Gönderme
KafkaTemplate, Kafka'ya mesaj göndermek için Spring'in sunduğu yüksek seviyeli API'dir:
@Service
@RequiredArgsConstructor
@Slf4j
public class OrderEventProducer {
private final KafkaTemplate<String, Object> kafkaTemplate;
// Basit gönderim — topic ve değer
public void publishOrderCreated(OrderEvent event) {
kafkaTemplate.send("order-events", event.getOrderId(), event);
// key=orderId → aynı siparişin event'leri aynı partition'a gider
// Bu, sıralılık garantisi sağlar (aynı key = aynı partition)
}
// CompletableFuture ile asenkron sonuç takibi
public void publishWithCallback(OrderEvent event) {
CompletableFuture<SendResult<String, Object>> future =
kafkaTemplate.send("order-events", event.getOrderId(), event);
future.whenComplete((result, ex) -> {
if (ex == null) {
RecordMetadata metadata = result.getRecordMetadata();
log.info("✅ Message sent — topic={}, partition={}, offset={}",
metadata.topic(), metadata.partition(), metadata.offset());
} else {
log.error("❌ Failed to send: key={}", event.getOrderId(), ex);
// Retry, DLQ veya alert mekanizması
retryService.scheduleRetry("order-events", event);
}
});
}
// Header ekleyerek gönderme
public void publishWithHeaders(OrderEvent event) {
ProducerRecord<String, Object> record =
new ProducerRecord<>("order-events", event.getOrderId(), event);
record.headers()
.add("event-type", "ORDER_CREATED".getBytes())
.add("source", "order-service".getBytes())
.add("correlation-id", UUID.randomUUID().toString().getBytes())
.add("timestamp", String.valueOf(System.currentTimeMillis()).getBytes());
kafkaTemplate.send(record);
}
// Belirli partition'a gönderme
public void publishToPartition(OrderEvent event, int partition) {
kafkaTemplate.send("order-events", partition, event.getOrderId(), event);
}
}Key Seçimi — Neden Önemli?
Kafka'da key seçimi partition dağılımını belirler:
key = null → Round-robin (her mesaj farklı partition'a)
key = orderId → Aynı siparişin TÜM event'leri aynı partition'a
→ SIRAYLA işlenir (created → paid → shipped)
key = userId → Aynı kullanıcının tüm event'leri aynı partition'a
Kural: Sıralılık gerekiyorsa aynı key kullanın.
Eşit dağılım istiyorsanız null veya random key kullanın.@KafkaListener ile Mesaj Alma
@KafkaListener, Spring Kafka'nın consumer tarafındaki temel anotasyonudur:
@Service
@Slf4j
public class OrderEventConsumer {
// Basit listener — otomatik deserialization
@KafkaListener(topics = "order-events", groupId = "order-service")
public void handleOrderEvent(OrderEvent event) {
log.info("📦 Received: orderId={}", event.getOrderId());
orderProcessingService.process(event);
}
// ConsumerRecord ile tam erişim (metadata + headers)
@KafkaListener(topics = "order-events", groupId = "analytics-service")
public void handleWithMetadata(ConsumerRecord<String, OrderEvent> record) {
log.info("Topic: {}, Partition: {}, Offset: {}, Key: {}, Timestamp: {}",
record.topic(), record.partition(), record.offset(),
record.key(), record.timestamp());
// Header'lara erişim
record.headers().forEach(header ->
log.debug("Header: {}={}", header.key(), new String(header.value())));
analyzeOrder(record.value());
}
// Manuel acknowledgement — offset commit kontrolü
@KafkaListener(topics = "payment-events", groupId = "payment-processor")
public void handlePayment(PaymentEvent event, Acknowledgment ack) {
try {
paymentService.process(event);
ack.acknowledge(); // Başarılı — offset'i commit et
log.info("✅ Payment processed and acknowledged: {}", event.getPaymentId());
} catch (RetryableException e) {
// ACK göndermiyoruz → mesaj tekrar teslim edilir
log.warn("⚠️ Retryable error — will be redelivered: {}", e.getMessage());
throw e;
} catch (Exception e) {
// Kalıcı hata — loglayıp ACK gönder (DLT ile yakalanacak)
log.error("❌ Permanent failure: {}", event.getPaymentId(), e);
ack.acknowledge(); // Sonsuz döngüyü önle
}
}
// Birden fazla topic dinleme
@KafkaListener(topics = {"order-events", "return-events"}, groupId = "order-service")
public void handleMultipleTopics(
@Payload Object event,
@Header(KafkaHeaders.RECEIVED_TOPIC) String topic,
@Header(KafkaHeaders.RECEIVED_PARTITION) int partition,
@Header(KafkaHeaders.OFFSET) long offset) {
log.info("Event from topic={}, partition={}, offset={}: {}",
topic, partition, offset, event);
}
// Batch (toplu) mesaj işleme
@KafkaListener(topics = "log-events", groupId = "log-aggregator",
containerFactory = "batchFactory")
public void handleBatch(List<LogEvent> events) {
log.info("📦 Received batch of {} log events", events.size());
logRepository.saveAll(events); // Toplu kayıt — çok daha verimli
}
}Programatik Konfigürasyon
@Configuration
public class KafkaConfig {
@Value("${spring.kafka.bootstrap-servers}")
private String bootstrapServers;
// Producer factory
@Bean
public ProducerFactory<String, Object> producerFactory() {
Map<String, Object> config = new HashMap<>();
config.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers);
config.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class);
config.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, JsonSerializer.class);
config.put(ProducerConfig.ACKS_CONFIG, "all");
config.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true);
config.put(ProducerConfig.RETRIES_CONFIG, 3);
config.put(ProducerConfig.COMPRESSION_TYPE_CONFIG, "snappy");
config.put(ProducerConfig.BATCH_SIZE_CONFIG, 32768);
config.put(ProducerConfig.LINGER_MS_CONFIG, 20);
return new DefaultKafkaProducerFactory<>(config);
}
@Bean
public KafkaTemplate<String, Object> kafkaTemplate() {
return new KafkaTemplate<>(producerFactory());
}
// Consumer factory
@Bean
public ConsumerFactory<String, Object> consumerFactory() {
Map<String, Object> config = new HashMap<>();
config.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers);
config.put(ConsumerConfig.GROUP_ID_CONFIG, "order-service");
config.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
config.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, JsonDeserializer.class);
config.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
config.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, false);
config.put(ConsumerConfig.MAX_POLL_RECORDS_CONFIG, 100);
config.put(JsonDeserializer.TRUSTED_PACKAGES, "com.example.*");
return new DefaultKafkaConsumerFactory<>(config);
}
// Standard listener container factory
@Bean
public ConcurrentKafkaListenerContainerFactory<String, Object> kafkaListenerContainerFactory() {
ConcurrentKafkaListenerContainerFactory<String, Object> factory =
new ConcurrentKafkaListenerContainerFactory<>();
factory.setConsumerFactory(consumerFactory());
factory.setConcurrency(3); // 3 consumer thread
factory.getContainerProperties().setAckMode(ContainerProperties.AckMode.MANUAL_IMMEDIATE);
return factory;
}
// Batch listener factory
@Bean
public ConcurrentKafkaListenerContainerFactory<String, Object> batchFactory() {
ConcurrentKafkaListenerContainerFactory<String, Object> factory =
new ConcurrentKafkaListenerContainerFactory<>();
factory.setConsumerFactory(consumerFactory());
factory.setBatchListener(true);
factory.setConcurrency(3);
return factory;
}
}Error Handling ve Dead Letter Topic (DLT)
DefaultErrorHandler
@Configuration
public class KafkaErrorConfig {
@Bean
public DefaultErrorHandler errorHandler(KafkaOperations<String, Object> template) {
// İşlenemeyen mesajları DLT topic'e yönlendirme
DeadLetterPublishingRecoverer recoverer = new DeadLetterPublishingRecoverer(
template,
(record, ex) -> new TopicPartition(
record.topic() + ".DLT", // order-events → order-events.DLT
record.partition()
)
);
// 3 deneme, 1 saniye aralıkla
DefaultErrorHandler handler = new DefaultErrorHandler(
recoverer,
new FixedBackOff(1000L, 3L)
);
// Retry yapılmaması gereken exception'lar
handler.addNotRetryableExceptions(
DeserializationException.class,
IllegalArgumentException.class,
ClassCastException.class
);
return handler;
}
}@RetryableTopic — En Güçlü Çözüm
Spring Kafka 2.7+ ile gelen @RetryableTopic, otomatik retry topic'leri oluşturur:
@KafkaListener(topics = "order-events", groupId = "order-service")
@RetryableTopic(
attempts = "3",
backoff = @Backoff(delay = 1000, multiplier = 2, maxDelay = 10000),
dltTopicSuffix = ".DLT",
autoCreateTopics = "true",
topicSuffixingStrategy = TopicSuffixingStrategy.SUFFIX_WITH_INDEX_VALUE
)
public void handleOrder(OrderEvent event) {
orderService.processOrder(event);
// Hata fırlatırsa:
// 1. deneme: order-events-retry-0 (1s sonra)
// 2. deneme: order-events-retry-1 (2s sonra)
// 3. deneme: order-events-retry-2 (4s sonra)
// Hâlâ başarısızsa: order-events.DLT
}
@DltHandler // DLT'ye düşen mesajları yakalar
public void handleDlt(OrderEvent event,
@Header(KafkaHeaders.RECEIVED_TOPIC) String topic,
@Header(KafkaHeaders.EXCEPTION_MESSAGE) String errorMessage) {
log.error("☠️ DLT — topic={}, event={}, error={}", topic, event, errorMessage);
alertService.notify("Order processing failed permanently: " + event.getOrderId());
// Manuel müdahale gerekir — ticket aç, admin bilgilendir
}Consumer Group ve Partition İlişkisi
Topic: order-events (6 partition)
Consumer Group: order-service (3 consumer instance)
Dağılım:
Consumer-1: Partition 0, 1
Consumer-2: Partition 2, 3
Consumer-3: Partition 4, 5
Kurallar:
- Bir partition sadece bir consumer tarafından okunur (aynı group içinde)
- Consumer sayısı > partition sayısı → fazla consumer boşta kalır
- Consumer çökerse → partition'ları diğer consumer'lara rebalance edilir
Concurrency ayarı:
spring.kafka.listener.concurrency=3 → 3 consumer thread
Partition sayısı kadar veya daha az concurrency ayarlayın
6 partition için concurrency=6 optimalYaygın Hatalar
1. Trusted Packages Ayarlanmamış
# ❌ "The class is not in the trusted packages" hatası
# JsonDeserializer, güvenlik nedeniyle sadece belirtilen paketleri kabul eder
# ✅ ÇÖZÜM
spring.kafka.consumer.properties.spring.json.trusted.packages: "com.example.*"2. Auto-commit ile Mesaj Kaybı
# ❌ enable-auto-commit: true → mesaj işlenmeden offset commit'lenebilir
# Consumer çökerse işlenmemiş mesajlar kaybolur
# ✅ enable-auto-commit: false + ack-mode: manual_immediate
spring.kafka.consumer.enable-auto-commit: false
spring.kafka.listener.ack-mode: manual_immediate3. Concurrency > Partition Sayısı
# ❌ 3 partition, 10 concurrency → 7 consumer boşta kalır (kaynak israfı)
# ✅ concurrency ≤ partition sayısıÖzet
Spring Kafka,
KafkaTemplate(gönderme) ve@KafkaListener(alma) ile Kafka entegrasyonunu soyutlar. JSON serialization ile tip-güvenli mesajlaşma sağlar.Key seçimi partition dağılımını belirler. Sıralılık gerekiyorsa aynı key kullanın (orderId, userId). Eşit dağılım istiyorsanız null key kullanın.
Manuel offset commit (
ack-mode: manual_immediate) ile mesaj kaybını önleyin. Auto-commit, mesaj işlenmeden commit'lenme riskini taşır.@RetryableTopic ile otomatik retry topic'leri ve DLT oluşturun.
@DltHandlerile kalıcı hataları yakalayıp alert gönderin.Concurrency, partition sayısına eşit veya daha az olmalı. Fazla consumer boşta kalır.
Idempotent producer (
enable.idempotence=true) ile duplicate mesajları engelleyin.acks=allile tüm replica'ların onayını bekleyin.
Gerçek Dünya Örneği: Event-Driven Sipariş Sistemi
// ═══════════════════════════════════════════
// Producer — Sipariş servisi
// ═══════════════════════════════════════════
@Service
@RequiredArgsConstructor
@Slf4j
public class OrderKafkaProducer {
private final KafkaTemplate<String, Object> kafkaTemplate;
public void publishOrderLifecycleEvent(Order order, String eventType) {
OrderKafkaMessage message = OrderKafkaMessage.builder()
.orderId(order.getId().toString())
.customerId(order.getCustomerId().toString())
.totalAmount(order.getTotalAmount())
.eventType(eventType)
.items(order.getItems().stream()
.map(i -> new ItemMessage(i.getProductId(), i.getQuantity(), i.getPrice()))
.toList())
.timestamp(Instant.now())
.build();
// Key = orderId → aynı siparişin tüm event'leri sıralı işlenir
ProducerRecord<String, Object> record = new ProducerRecord<>(
"order-lifecycle", order.getId().toString(), message);
record.headers().add("event-type", eventType.getBytes());
kafkaTemplate.send(record).whenComplete((result, ex) -> {
if (ex != null) {
log.error("Failed to publish {} for order {}", eventType, order.getId(), ex);
}
});
}
}
// ═══════════════════════════════════════════
// Consumer — Envanter servisi
// ═══════════════════════════════════════════
@Component
@Slf4j
public class InventoryKafkaConsumer {
@KafkaListener(
topics = "order-lifecycle",
groupId = "inventory-service",
containerFactory = "kafkaListenerContainerFactory"
)
@RetryableTopic(attempts = "3", backoff = @Backoff(delay = 2000, multiplier = 2))
public void handleOrderEvent(
OrderKafkaMessage message,
Acknowledgment ack,
@Header("event-type") String eventType) {
try {
switch (eventType) {
case "CREATED" -> {
log.info("📦 Stok ayırma: orderId={}", message.getOrderId());
inventoryService.reserveStock(message.getItems());
}
case "CANCELLED" -> {
log.info("📦 Stok iade: orderId={}", message.getOrderId());
inventoryService.releaseStock(message.getItems());
}
case "SHIPPED" -> {
log.info("📦 Stok düşürme (kesinleştirme): orderId={}", message.getOrderId());
inventoryService.confirmReservation(message.getItems());
}
}
ack.acknowledge();
} catch (InsufficientStockException e) {
log.error("Yetersiz stok — sipariş iptal edilecek: {}", message.getOrderId());
// Kompensasyon: sipariş iptal event'i yayınla
compensationProducer.publishOrderCancellation(message.getOrderId(), "OUT_OF_STOCK");
ack.acknowledge(); // İşlendi sayılır (kompensasyon başlatıldı)
}
}
@DltHandler
public void handleDlt(OrderKafkaMessage message) {
log.error("☠️ DLT: İşlenemeyen sipariş event'i — orderId={}", message.getOrderId());
alertService.sendCritical("Inventory processing permanently failed: " + message.getOrderId());
}
}
// ═══════════════════════════════════════════
// Consumer — Analitik servisi (batch processing)
// ═══════════════════════════════════════════
@Component
@Slf4j
public class AnalyticsKafkaConsumer {
@KafkaListener(
topics = "order-lifecycle",
groupId = "analytics-service",
containerFactory = "batchFactory"
)
public void handleBatch(List<ConsumerRecord<String, OrderKafkaMessage>> records) {
log.info("📊 Batch analytics: {} event işleniyor", records.size());
List<AnalyticsEntry> entries = records.stream()
.map(record -> AnalyticsEntry.builder()
.eventType(new String(record.headers().lastHeader("event-type").value()))
.orderId(record.value().getOrderId())
.amount(record.value().getTotalAmount())
.timestamp(record.value().getTimestamp())
.build())
.toList();
analyticsRepository.saveAll(entries); // Toplu kayıt — performans
}
}Bu mimari ile sipariş yaşam döngüsündeki her event, ilgili tüm servisler tarafından bağımsız olarak işlenir. Envanter servisi stok yönetimini, analitik servisi veri analizini, bildirim servisi kullanıcı iletişimini yapar — hepsi aynı Kafka topic'inden, kendi consumer group'larıyla.
AI Asistan
Sorularını yanıtlamaya hazır