공통 이벤트 처리 설계 및 구축 - Genie-Uss/genieus GitHub Wiki

🎯 핵심 목표

  • Kafka 기반의 이벤트를 서비스별로 자동 등록된 핸들러 메서드로 안전하고 구조적으로 라우팅
  • 제너릭 타입 포함 이벤트도 역직렬화가 가능한 구조 설계
  • 각 서비스에서 핸들러, 폴백, 타입 매핑을 애너테이션 기반으로 선언적으로 등록
  • 도메인 이벤트 표준화, 재사용 가능한 공통 컴포넌트 제공

⚙️ 주요 기술 스택 및 아키텍처 요소

  • Spring BeanPostProcessor: 핸들러 메서드를 런타임에 스캔하고 자동 등록
  • 커스텀 어노테이션: @EventTypeMapping, @FallbackMapping 도입으로 선언적 라우팅 및 폴백 지정
  • Generic Type-safe JSON 역직렬화: Jackson의 TypeReference를 활용해 제네릭 타입도 역직렬화 처리
  • EventDispatcher / EventRouter / EventEnvelopeParser 구성: 이벤트 수신 → 타입 확인 → 역직렬화 → 핸들러 전달 → 예외 시 폴백
  • EventTypeRegistry: 이벤트 타입명 ↔ 클래스 매핑 캐시 관리
  • AOP는 사용하지 않고, 순수 DI 및 후처리 기반 구조 유지

🧱 라이브러리 구성 요소 및 역할

1. @EventTypeMapping, @FallbackMapping

  • 각 서비스는 이벤트 핸들러 메서드에 @EventTypeMapping("OrderCanceled")와 같은 방식으로 이벤트 바인딩
  • 예외 발생 시 대체 처리 로직을 @FallbackMapping("OrderCanceled") 으로 명시

2. EventHandlerBeanPostProcessor

  • Bean 초기화 이후 모든 Bean의 메서드를 탐색해 커스텀 애노테이션이 달린 메서드들을 등록
  • EventDispatcher에 이벤트 타입 기반 핸들러와 폴백을 자동으로 매핑
  • EventTypeRegistry에 이벤트 클래스도 등록해 이후 역직렬화 시 활용

3. EventEnvelopeParser

  • Kafka 메시지 JSON에서 이벤트 타입을 추출하고, 등록된 클래스 정보를 기반으로 역직렬화 수행
  • EventEnvelope<T>로 감싼 메시지 구조를 파싱하여 타입 안정성 확보

4. EventDispatcher, EventRouter

  • Dispatcher는 파싱된 이벤트를 핸들러에 전달하고, 예외 발생 시 폴백을 호출
  • Router는 Kafka 리스너가 받은 메시지를 파싱 → 디스패치 → 폴백 처리 전체 흐름을 관리

📈 적용 효과

  • MSA 환경에서 각 도메인 서비스가 중복 없는 방식으로 통일된 이벤트 처리 구조를 가지게 됨
  • 도메인 이벤트의 정형화된 표준 처리 파이프라인 확보
  • 역직렬화 오류 방지 및 예외 상황 자동 대응으로 운영 안정성 향상
  • 핸들러 메서드만 선언하면 자동 등록되므로, 신규 이벤트 추가 시 생산성 대폭 향상

📌 시각화 다이어그램 (Mermaid 기반)

  • Kafka 수신부터 핸들러 호출 및 예외 폴백까지의 전체 흐름

  • 애플리케이션 컨텍스트 초기화 시 핸들러 자동 등록 과정

  • 시퀀스 다이어그램

    
sequenceDiagram
    participant Kafka
    participant EventRouter
    participant EventEnvelopeParser
    participant EventDispatcher
    participant HandlerBean

    Kafka->>EventRouter: Kafka 메시지 수신 (topic, json)
    EventRouter->>EventEnvelopeParser: 이벤트 타입 추출 및 클래스 확인 (resolveEventType)
    EventEnvelopeParser-->>EventRouter: 이벤트 클래스 반환
    EventRouter->>EventEnvelopeParser: JSON 역직렬화 (deserialize)
    EventEnvelopeParser-->>EventRouter: EventEnvelope 반환
    EventRouter->>EventDispatcher: 이벤트 디스패치 (dispatch)
    EventDispatcher->>HandlerBean: 이벤트 핸들러 메서드 호출
    HandlerBean-->>EventDispatcher: 처리 완료

    alt 핸들러 예외 발생 시
        EventDispatcher->>EventRouter: 예외 발생
        EventRouter->>EventDispatcher: 폴백 실행 요청 (fallback)
        EventDispatcher->>HandlerBean: 폴백 메서드 호출
    end


    sequenceDiagram
    participant SpringContext
    participant BeanPostProcessor
    participant EventDispatcher
    participant EventTypeRegistry

    SpringContext->>BeanPostProcessor: 빈 초기화 후 후처리
    BeanPostProcessor->>BeanPostProcessor: @EventTypeMapping, @FallbackMapping 메서드 탐색
    BeanPostProcessor->>EventDispatcher: 핸들러 및 폴백 등록 (register)
    BeanPostProcessor->>EventTypeRegistry: 이벤트 타입-클래스 매핑 등록 (register)

🧪 기여도 및 개인 역할

  • 전체 아키텍처 설계 및 라이브러리 구현 100%
  • 공통 모듈화 및 각 도메인 서비스에 적용하여 이벤트 전파 성공률 99% 이상 유지
  • 제네릭 타입 처리 및 JSON 파싱 문제 해결 경험 공유 및 문서화