결제 라우터에 옵션 추가하며 6개 도메인과 용어 체계를 한번에 정비

결제 라우터에 옵션 C를 추가하면서, 관련된 거의 모든 도메인 레이어를 한 번에 건드렸다.

이 작업이 왜 한꺼번에 터졌냐면

결제 라우터에 새로운 경로(옵션 C)를 감싸는(wrap) 작업은 사실 단순히 PaymentAdapter 한 파일만 수정하면 끝날 것 같지만, 실제로는 그렇지 않다. 결제 흐름은 시스템 전체에 걸쳐 있어서, 라우팅 옵션 하나가 추가되면 그 옵션을 인지하고 처리해야 하는 지점이 도메인 레이어 전반에 퍼져 있다.

이번 커밋에서 건드린 파일 목록을 보면 딱 감이 온다:

여기다 PG 관제 어드민까지 이번에 함께 들어갔다. 관제 어드민은 "라우터 옵션이 하나 더 생겼을 때 운영자가 어떤 화면에서 뭘 볼 수 있어야 하는가"에 대한 답변이다. 코드만 짜고 관제 UI가 없으면 장애 발생 시 블랙박스가 되기 때문에, 옵션 추가와 관제 도구는 항상 같이 가야 한다는 게 내 기준이다.

어휘 친화 작업, 왜 같이 했냐

커밋 메시지에 "어휘 친화"라는 표현이 들어간 이유가 있다. 옵션 C를 추가하면서 기존 코드에서 사용하던 결제 관련 용어들이 일관성 없이 혼재돼 있는 게 눈에 띄었다. 예를 들어 같은 개념인데 어떤 클래스에서는 payType, 어떤 곳에서는 paymentMethod, 또 어떤 곳에서는 chargeKind로 불리고 있었다.

// 어휘 정리 전
String payType = request.getPayType();         // order
String paymentMethod = dto.getPaymentMethod(); // charge
String chargeKind = param.getChargeKind();     // member
// → 같은 개념, 다른 이름

// 어휘 정리 후 (추상화 레이어 기준으로 통일)
PaymentRoute route = PaymentRoute.from(request.getRouteCode());
// charge, order, member 모두 동일한 enum 참조

팀 입장에서 이게 왜 중요하냐면, 새로운 팀원이 코드 리뷰 들어오거나 장애 대응할 때 용어가 통일되지 않으면 커뮤니케이션 비용이 배가 된다. 슬랙에서 "옵션 C가 payType=3이냐 routeCode=C냐"를 물어보는 상황이 생기면 이미 늦은 거다.

이런 작업을 할 때 내가 체크하는 것들

• wrap은 기존 코드를 건드리지 않는 방향으로: 옵션 A, B 흐름은 그대로 두고 옵션 C만 새 레이어로 감싼다. 기존 테스트가 깨지면 안 됨.
• 관제 어드민은 코드 배포와 동시에: 운영 환경에서 옵션 C 트래픽이 들어오기 시작하는 순간부터 모니터링이 가능해야 한다. 배포 먼저, 관제 나중은 없다.
• 어휘 정리는 기능 변경과 커밋을 분리하는 게 이상적이지만: 현실에서는 옵션 추가 작업을 하다가 눈에 밟히는 걸 참기가 어렵다. 다만 이걸 같이 묶을 때는 반드시 PR 설명에 "기능 변경"과 "리팩터링" 영역을 분리해서 적어둔다. 리뷰어가 두 가지를 한꺼번에 봐야 한다면 최소한 어느 부분이 어느 성격인지는 알고 봐야 하니까.

도메인 6개를 한 커밋에 넣은 건 이상적이지 않다는 걸 안다. 하지만 결제 옵션 추가라는 기능이 도메인 경계를 자연스럽게 가로지르는 작업이라, 중간 상태로 머지하면 오히려 컴파일조차 안 되는 구간이 생긴다. 이런 상황에서는 도메인별로 쪼개는 것보다 atomic하게 한 번에 가져가는 게 팀 전체 맥락에서 더 안전하다고 판단했다. 논쟁의 여지는 있지만, 그게 이번 선택의 이유였다.

다음

🛒 이 글과 어울리는 추천 상품

• 외장SSD 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.