← Kursa Dön
📄 Text · 30 min

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 optimal

Yaygı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_immediate

3. 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. @DltHandler ile 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=all ile 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.