입금 웹훅 구조를 레지스트리 패턴으로 전환해 은행 추가 용이성 개선

배경

연락처 송금 기능에 입금 통보 받을 은행이 한 곳 더 늘어남. 기존엔 진입 컨트롤러에서 은행 코드별 if-else로 분기하던 구조라 추가할 때마다 같은 파일을 또 건드려야 했음. 이번에 인터넷전문은행 한 곳 더 붙이라는 요청 받았는데, 같은 자리를 또 손대기 싫어서 레지스트리 패턴으로 갈아엎기로 함.

무엇을 바꿨나

• 결제대행사 웹훅 수신 진입점은 그대로 두고, 은행 코드별로 핸들러를 찾아 위임하는 레지스트리를 둠
• 공통 입금 후처리(파트너 잔액 갱신, 송금 큐 상태 전이, 알림 발송)는 유틸로 분리
• 신규 은행 핸들러는 인터페이스만 구현하면 자동 등록되게 함

삽질

처음엔 인터페이스 하나 빼고 빈 등록만 하면 끝날 줄 알았음. 근데 입금 통보 페이로드가 은행마다 미묘하게 달라서, 공통 DTO로 받자니 옵셔널 필드가 폭증함. 결국 핸들러가 자기 페이로드를 직접 파싱하고 표준 입금 이벤트로 변환해서 유틸에 넘기는 식으로 정리. 컨트롤러는 raw body + 헤더만 던져줌.

웹훅 수신
 → 은행코드 추출
 → 레지스트리.find(은행코드)
 → 핸들러.parse(raw)
 → 공통유틸.처리(표준이벤트)

검증

• 이커머스 파트너 두 곳 대상 입금 시뮬레이션으로 잔액·큐 상태 동일성 확인
• 기존 은행 회귀 케이스 8건 모두 통과
• 신규 인터넷전문은행 페이로드는 결제 플랫폼 샌드박스로 5건 받아 처리 결과 비교

느낀 점과 남은 일

• 핸들러 패턴 자체는 흔한데, 결제 도메인에서는 도메인 이벤트 표준화가 절반임을 다시 체감. 입력 모양이 다 달라서 표준화 안 하면 결국 if-else가 유틸 안으로 옮겨갈 뿐
• 핸들러별 테스트 픽스처가 핸들러 폴더에 흩어져 있어서, 한 번 모아둘 예정
• 입금 실패·중복 통보 처리는 유틸에서 일괄 처리 중인데, 은행마다 재시도 정책이 달라서 후속으로 분리 필요

다음