[트러블슈팅] : Kafka 역직렬화 오류 - trusted packages 불일치

상황

주문 생성 API를 호출하면 응답은 정상적으로 왔지만, 콘솔 로그에 아래 에러가 무한히 반복됐다.

The class 'com.example.gigacoffee.common.model.kafka.event.PaymentConfirmedEvent'
is not in the trusted packages:
[com.example.gigacoffee.common.kafka.model.event]

원인 분석

리팩터링 과정에서 PaymentConfirmedEvent의 패키지 경로가 변경됐다.

변경 전: com.example.gigacoffee.common.model.kafka.event
변경 후: com.example.gigacoffee.common.kafka.model.event

Kafka Producer는 이벤트를 발행할 때 메시지 헤더에 클래스의 패키지 경로를 담아서 보낸다.

메시지 헤더: __TypeId__ = com.example.gigacoffee.common.model.kafka.event.PaymentConfirmedEvent

리팩터링 전에 이미 브로커에 발행된 메시지 헤더에는 구 패키지 경로가 박혀 있었다. Consumer의 trusted packages에는 새 패키지 경로만 등록돼 있어서 역직렬화를 거부한 것이다. offset이 진행되지 않아 같은 메시지를 계속 재시도하면서 에러가 무한 반복됐다.

해결 방법

개발 환경에서는 Kafka 토픽을 초기화하는 것이 가장 빠르고 깔끔하다.

docker-compose down -v
docker-compose up -d

볼륨까지 삭제하면 브로커에 쌓인 기존 메시지가 전부 사라지고 에러가 해결된다.

운영 환경이라면 토픽 초기화가 불가능하므로 trusted packages에 구 패키지 경로를 추가하거나, offset을 강제로 이동시키는 방법을 사용해야 한다.

props.put(JsonDeserializer.TRUSTED_PACKAGES,
    "com.example.gigacoffee.common.kafka.model.event," +
    "com.example.gigacoffee.common.model.kafka.event");

인사이트

Kafka Producer는 메시지 헤더에 클래스 패키지 경로를 포함해서 발행한다. 패키지 경로를 변경하는 리팩터링을 할 때는 브로커에 이미 발행된 메시지와의 호환성을 반드시 고려해야 한다. 개발 환경에서는 토픽을 주기적으로 초기화하는 습관을 들이면 이런 문제를 예방할 수 있다.