---
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`를 남겨 추적 가능하게 하라.

## 적용 절차

1. 이벤트 스키마를 확정하고 `*Event` 타입을 정의하라.
2. `*EventHandler`를 생성하고 `handle` 진입점을 고정하라.
3. 핸들러 내부 로직을 라우팅/위임 중심으로 제한하라.
4. 동기/비동기 이벤트별 실패 정책(전파/재시도/데드레터)을 먼저 확정하라.
5. 중복 처리 방지(멱등 키/상태 확인)를 반영하라.
6. 실패/재시도 시 동작을 예외 정책과 로그로 명확히 하라.

## 빠른 체크리스트

- 클래스명이 `*EventHandler`로 끝나는가?
- 입력 타입이 `*Event`인가?
- 핸들러가 비즈니스 로직을 직접 수행하지 않는가?
- 이벤트 생성/발행 책임이 핸들러에 섞여 있지 않은가?
- 동기/비동기 실패 정책이 정의됐는가?
- 중복 이벤트 수신 시 안전한가?
- 운영 로그에 이벤트 식별자가 남는가?