결제 플랫폼 서버 기동 실패, 컨트롤러 빈 이름 충돌로 해결

서버가 안 뜸

오전에 결제 플랫폼 모듈 한 군데 손보고 로컬에 띄우는데 기동 자체가 실패함. 로그 끝부분만 잘라보면 "동일한 빈 이름이 이미 정의되어 있다"는 메시지가 떡하니 박혀 있었음. 코드는 컴파일 통과했는데 컨테이너 초기화 단계에서 막힌 케이스.

원인 추적

기존에 사업자 정보 확인용 컨트롤러가 하나 있었는데, 며칠 전 다른 도메인에서 비슷한 검증 기능을 만들면서 단순 클래스명을 똑같이 가져갔음. 패키지가 달라서 자바 입장에선 다른 타입이지만, 컨테이너는 클래스 단순명을 소문자로 낮춘 값을 빈 이름으로 등록함. 결과는 충돌.

# 기존
package a.x.controller
class XxxCheck { }   // 빈 이름: xxxCheck

# 신규로 추가된 쪽
package b.y.controller
class XxxCheck { }   // 빈 이름: xxxCheck  ← 동일

처리한 방법

• 명시적 빈 이름을 부여해서 충돌 회피
• 신규 쪽 클래스명 자체를 도메인 의미 살려서 리네이밍
• 둘 다 가능했지만 후자가 가독성 압도적

이번엔 신규로 추가한 쪽이 이름이 너무 일반적이었음. 어차피 의미를 못 담고 있었으니, 도메인 접두사 붙여서 리네이밍하는 쪽으로 정리. 빌드/기동 한 번에 통과.

회고

• 메시지가 친절한 편이라 디버깅 자체는 5분 컷. 진짜 문제는 리뷰 단계에서 못 잡았다는 것.
• 컨벤션 추가: 컨트롤러 클래스명에 도메인 접두사 강제. 단순명 단독 사용은 거의 무조건 충돌 후보.
• 빈 이름 충돌은 정적 분석 도구로도 잡을 수 있는 케이스라, 다음 스프린트 때 린트 룰 하나 추가하는 걸로 메모.
• 로컬 풀빌드 안 띄우고 모듈 단위로만 돌리는 동료들은 발견조차 못 했을 이슈. 기동 단계 검증을 PR 체크에 묶어두는 게 답.

작은 충돌이었지만 "패키지가 다르면 안전하다"는 무의식적 가정이 깨진 케이스였음. 빈 이름은 패키지 무시하고 평면이라는 사실을 또 한 번 새김.

다음