name: eventhandler-conventions description: Java Spring EventHandler 레이어 규칙을 적용한다. 이벤트 핸들러 네이밍, 이벤트 입력 모델, 처리 흐름, 멱등성/재처리 기준 정리가 필요할 때 사용한다.
EventHandler Conventions
목표
- EventHandler를 이벤트 수신/라우팅 계층으로 유지하라.
- 핸들러 내부 비즈니스 로직을 최소화하고 시나리오 실행으로 위임하라.
- 이 스킬은 EventHandler 규칙만 다루고 다른 레이어 세부 규칙은 다루지 마라.
네이밍 규칙
- 클래스:
*EventHandler - 입력 이벤트:
*Event - 핸들러 메서드:
handle(*Event event) - 이벤트 타입명: 과거형 동사 기반 (
UserRegisteredEvent,MemberRoleChangedEvent)
레이어 규칙
- EventHandler는 이벤트 파싱/기본 검증/라우팅만 담당하라.
- 비즈니스 규칙 구현은 핸들러에서 직접 처리하지 마라.
- 중복 이벤트 수신을 고려해 멱등하게 작성하라.
- 재시도 가능한 실패와 즉시 실패를 구분해 예외를 처리하라.
- 로그에
eventId,eventType,aggregateId를 포함하라.
이벤트 처리 규칙
- EventHandler는 이벤트 처리만 담당한다. 이벤트 생성/발행 책임은 두지 마라.
- EventHandler는 자기 도메인의
UseCase만 참조하라. 동기 이벤트핸들러 실패는 호출 흐름 실패로 전파하라.비동기 이벤트핸들러 실패는 재시도/데드레터 정책을 따르라.- 멱등성 키 기준으로 중복 처리를 방지하라.
- 로그에
eventId,eventType,aggregateId를 남겨 추적 가능하게 하라.
적용 절차
- 이벤트 스키마를 확정하고
*Event타입을 정의하라. *EventHandler를 생성하고handle진입점을 고정하라.- 핸들러 내부 로직을 라우팅/위임 중심으로 제한하라.
- 동기/비동기 이벤트별 실패 정책(전파/재시도/데드레터)을 먼저 확정하라.
- 중복 처리 방지(멱등 키/상태 확인)를 반영하라.
- 실패/재시도 시 동작을 예외 정책과 로그로 명확히 하라.
빠른 체크리스트
- 클래스명이
*EventHandler로 끝나는가? - 입력 타입이
*Event인가? - 핸들러가 비즈니스 로직을 직접 수행하지 않는가?
- 이벤트 생성/발행 책임이 핸들러에 섞여 있지 않은가?
- 동기/비동기 실패 정책이 정의됐는가?
- 중복 이벤트 수신 시 안전한가?
- 운영 로그에 이벤트 식별자가 남는가?