파트너 포털 계좌 조회 API 라우팅 중복 제거로 환경별 응답 불일치 해소

무슨 일이 있었나

파트너 포털 쪽 컨트롤러를 손보다가 같은 경로에 매핑된 핸들러가 두 개 있는 걸 발견함. 한쪽은 신규 응답 스펙으로 갈아탄 메서드, 다른 한쪽은 레거시 단건 계좌 조회 API였음. 둘 다 같은 URL을 물고 있어서 어느 쪽이 먼저 잡히는지 빌드 환경마다 다르게 나오는 게 본질적 문제였음.

운영에서는 신규 메서드가 먼저 잡혀 별 탈 없이 흘러가고 있었는데, 로컬에서 한 명이 "응답 필드가 안 맞는다"고 들고 옴. 까보니 레거시가 먼저 매칭돼서 옛날 포맷을 뱉고 있었음.

왜 살아남아 있었나

• 몇 분기 전에 신규 응답 스펙을 만들 때 레거시를 deprecated 처리하고 호출처만 옮긴 뒤 메서드 자체는 안 지웠음
• "혹시 외부에서 직접 때리면 어쩌나" 싶어 그대로 둔 게 누적됐음
• 그 사이 라우팅 우선순위가 바뀐 적이 있어서 환경별로 다른 응답이 나오는 잠재 버그가 됐음

어떻게 정리했나

변경 전: GET /accounts/{id} → 핸들러 2개 (신규/레거시)
변경 후: GET /accounts/{id} → 핸들러 1개

운 좋게 다른 충돌은 더 없었음. 콜백 로그까지 본 이유는 외부 시스템이 옛 경로를 직접 때리고 있을 가능성을 0으로 만들기 위해서였음. 호출 0건이 확인되니까 그제서야 마음 놓고 지웠음.

배운 점

• 라우팅 충돌은 빌드 순서·리플렉션 순서에 따라 달라져서 "내 환경에서는 잘 됨"이 가장 위험한 신호임
• deprecated 마킹만으로는 절대 안 죽음. 호출 0건 확인 + 실제 삭제까지 가야 정리됐다고 할 수 있음
• 비슷한 패턴이 다른 컨트롤러에도 있을 가능성이 큼. 다음 분기 정리 항목으로 적어뒀음
• 환경별로 다르게 동작하는 코드는 시한폭탄임. 발견 즉시 단일화하는 게 나중에 데일 일을 줄여줌

다음