Spring Kafka Consumer에서 Payload 값이 null일 때 발생하는 오류 해결 방법

Kafka를 활용한 메시지 처리 중, Consumer가 null Payload를 수신하면서 다음과 같은 MethodArgumentNotValidException이 발생할 수 있습니다.

Caused by: org.springframework.messaging.handler.annotation.support.MethodArgumentNotValidException: 
Could not resolve method parameter at index 0 ...
Payload value must not be empty

이 문제는 Kafka 메시지의 Payload가 null(KafkaNull)로 들어오는 경우 발생합니다. 이는 Kafka Producer가 null 값을 전송하거나, Tombstone 메시지(키에 대한 삭제 요청 메시지)가 전달된 경우입니다.

해결 방법

이 오류를 방지하고 안정적인 메시지 처리를 위해 아래와 같은 방법을 적용할 수 있습니다.

1. KafkaNull 허용 설정 (@Payload(required = false))

기본적으로 @Payload는 값이 없으면 예외를 발생시킵니다. 이를 방지하기 위해 required = false 옵션을 추가합니다.

샘플 코드

@KafkaListener(topics = "sample.topic.name", groupId = "sample-group")
public void processMessage(@Payload(required = false) SampleDto message,
                           Acknowledgment acknowledgment) throws Exception {
    if (message == null) {
        log.warn("Received KafkaNull message. Skipping processing...");
        return;
    }
    // 정상 메시지 처리 로직
}

@Payload(required = false)를 설정하면 null 값이 들어와도 예외가 발생하지 않습니다.
null이 들어왔을 때 로깅 후 메시지 처리를 건너뛰도록 구현합니다.

2. ConsumerRecord를 활용한 null 값 사전 필터링

Kafka 메시지의 null 값은 Tombstone 메시지일 가능성이 크므로, 이를 ConsumerRecord 레벨에서 필터링할 수 있습니다.

샘플 코드

@KafkaListener(topics = "sample.topic.name", groupId = "sample-group")
public void processMessage(ConsumerRecord<String, SampleDto> record,
                           Acknowledgment acknowledgment) throws Exception {
    if (record.value() == null) {
        log.warn("Received null message with key: {}", record.key());
        return;
    }
    // 메시지 처리 로직
}

ConsumerRecord<String, SampleDto>를 사용하면 null Payload뿐만 아니라, 해당 메시지의 키 값도 함께 확인할 수 있습니다.
record.value() == null 체크를 통해 KafkaNull 메시지를 사전에 필터링할 수 있습니다.

3. Producer에서 null 메시지 전송 확인

Producer에서 null 값을 전송하고 있는지 확인해야 합니다.
Kafka에서는 특정 키의 데이터를 삭제할 때 Tombstone 메시지(null Payload)를 전송할 수 있습니다.

샘플 코드

kafkaTemplate.send("sample.topic.name", "sample-key", null); // Tombstone 메시지 전송

Producer에서 null 값이 의도된 것인지 확인하고, 그렇지 않다면 빈 객체 대신 기본값을 설정하는 것이 좋습니다.

결론

Kafka Consumer에서 null Payload로 인한 오류를 해결하려면:
@Payload(required = false) 설정을 추가하여 null 허용
ConsumerRecord를 활용해 null 메시지 필터링
Producer에서 null Payload 전송 여부 점검

이러한 방법을 적용하면 Kafka Consumer에서 KafkaNull 메시지를 안정적으로 처리할 수 있습니다!