결제 플랫폼 빈 이름 충돌로 서버 부팅 실패 해결

빈 이름 충돌로 서버가 안 떴던 날

이커머스 결제 플랫폼 백엔드를 띄우는데 갑자기 부팅 실패. 로그 끝까지 내려가지도 않고 컨텍스트 초기화 단계에서 죽음. 처음엔 단순 의존성 문제인 줄 알았는데, 메시지를 천천히 읽어보니 빈 이름이 중복됐다는 얘기였음.

원인 찾기

스택을 위로 거슬러 올라가면서 확인한 것들:

• 같은 도메인의 컨트롤러 두 개가 동일한 빈 이름으로 등록되려 함
• 둘 다 디폴트 네이밍 규칙(클래스 단순명 → camelCase)을 그대로 사용
• 한쪽은 사업자 검증 신규 기능, 다른 쪽은 기존 레거시 파트너 검증 모듈

요약하면 두 컨트롤러가 같은 키를 두고 부딪힌 상황. 컨테이너 입장에서는 어느 쪽을 살려야 할지 결정 못 하니까 그냥 죽어버림.

해결

빠르게 우회하려면 두 가지 길:

1. 신규 컨트롤러에 명시적 이름을 부여해서 충돌만 회피
2. 디렉토리/네임스페이스를 정리해서 근본적으로 분리

당장은 1번으로 막고, 다음 PR에서 2번을 같이 가져가기로 함. 이름 명시 한 줄 추가하니 서버는 즉시 정상 부팅.

// 수정 전: 디폴트 이름 사용
// 수정 후: 빈 이름 명시 → 충돌 해소

회고 포인트

• 디폴트 네이밍은 편하지만 대규모 모놀리식에서는 시한폭탄. 같은 단어가 도메인을 가로질러 나타나는 순간 터짐
• 부팅 실패 류 이슈는 단위 테스트만으로는 못 잡음. 컨텍스트 로딩까지 도는 통합 레벨 검증이 PR 단계에 꼭 끼어 있어야 함
• 신규 컨트롤러를 만들 때 검색 한 번으로 같은 이름이 있는지 확인하는 습관이 결국 가장 싸게 먹힘

다음에 할 일

• 도메인별 컨트롤러 네임스페이스 규칙 문서화
• 부팅 실패를 머지 전에 잡도록 기본 검증 단계에 컨텍스트 로딩 스모크 추가
• 레거시 검증 모듈은 신규 쪽으로 단계적 흡수

같은 실수 두 번은 안 하면 됨. 끝