단일 토픽 환경에서의 메시지 분기 처리: Envelope DTO 패턴 vs 다형성 라우팅(@KafkaHandler)

• 분야: Spring Kafka, Message Routing, Payload Design
• 관련 파일: OrderEventConsumer.java

---

1. 배경: 토픽 통합으로 인한 식별 문제

직전에, 카프카 메시지 순서 역전(Out-of-Order) 문제를 해결하기 위해 인벤토리 서비스로 향하는 두 가지 명령(재고 차감, 재고 복구)을 개별 토픽에서 단일 토픽(inventory.command)으로 통합함

문제는 토픽이 하나로 합쳐지면서, 인벤토리 서비스의 컨슈머가 "지금 들어온 메시지가 차감 명령인지 복구 명령인지 어떻게 구분할 것인가?" 에 대한 아이디어가 잘 떠오르지 않았음...

2. 고민: 전통적인 Envelope(봉투) 패턴의 한계

가장 먼저 떠올린 해결책은 두 객체를 하나로 감싸는 거대한 '봉투(Envelope) DTO'를 만드는 것이었음

// 구상했던 Envelope DTO 구조
{
  "commandType": "RESERVE", // 또는 "RESTORE"
  "payload": {
     // 실제 데이터...
  }
}

하지만 이 방식을 도입할 경우 다음과 같은 치명적인 단점이 존재함:

1. 보일러플레이트 코드 증가: 오더 서비스와 인벤토리 서비스 양쪽에 공통 Envelope DTO를 만들어야 함.
2. 비즈니스 로직 오염: 컨슈머 내부에서 if-else 또는 switch-case 문을 통해 commandType을 검사하고 로직을 분기하는 지저분한 코드가 양산됨.

3. 해결: Spring Kafka의 __TypeId__ 헤더와 다형성 라우팅(@KafkaHandler)

명시적인 Envelope DTO를 만드는 대신, 프레임워크가 제공하는 방식인 '다형성(Polymorphic) 라우팅'을 활용하여 이 문제를 해결해보려고 시도함

[원리 및 적용 방식]

1. 자동 헤더 삽입: Spring Kafka는 JsonSerializer를 사용하여 메시지를 발행할 때, JSON 본문(Body)을 건드리지 않고 카프카 메시지 헤더에 __TypeId__: OrderCreatedEventPayload 라는 타입 정보를 함께 삽입함.
2. Type Mapping: 컨슈머 설정(application.yml)에서 spring.json.type.mapping을 통해 프로듀서의 패키지명과 컨슈머의 패키지명을 1:1로 매핑함.
3. 클래스 레벨 구독 및 메서드 라우팅: @KafkaListener를 메서드가 아닌 클래스 레벨로 끌어올리고, 각 메서드에는 @KafkaHandler를 부착함.

@Component
@KafkaListener(topics = "inventory.command") // 💡 단일 토픽 구독
public class OrderEventConsumer {

    // 💡 TypeId가 'OrderCreatedMessage'로 매핑되면 이 메서드 실행
    @KafkaHandler
    public void consumeOrderCreated(OrderCreatedMessage payload) {
        stockLockFacade.reserveOrderStocksWithLock(payload);
    }

    // 💡 TypeId가 'StockRestoreMessage'로 매핑되면 이 메서드 실행
    @KafkaHandler
    public void consumeStockRestoreRequest(StockRestoreMessage payload) {
        stockLockFacade.restoreStockWithLock(request);
    }
}

4. 성과 및 회고

이 방식을 채택함으로써 다음과 같은 이점을 얻을 수 있었음:

• 관심사의 분리(Separation of Concerns): 개발자는 메시지를 어떻게 라우팅할지 고민할 필요 없이, 각 비즈니스 객체(OrderCreatedMessage, StockRestoreMessage)의 처리에만 온전히 집중할 수 있게 되었음.
• 객체 지향적 설계: switch-case 문을 배제하고, 프레임워크가 런타임에 다형성을 이용해 올바른 메서드(Handler)를 찾아주는 구조를 완성함.
• 오버 엔지니어링 방지: 불필요한 Envelope DTO를 생성하지 않고, 카프카 프로토콜의 Native 메타데이터(Header)를 적극 활용하여 네트워크 페이로드 크기까지 최적화했음.

결과적으로, 단일 토픽 통합으로 발생할 수 있었던 라우팅의 복잡성을 Spring Kafka의 핵심 기능을 활용함으로써 해결해낼 수 있었음