결제 프로바이더 응답 키를 상수로 모아 리팩터링

결제 어댑터 레이어 내부를 정리하는 작업을 했다. 구체적으로는 특정 결제 프로바이더의 응답을 파싱할 때 쓰던 Map 키 문자열들을 상수로 뽑아낸 리팩터링이다.

왜 이 작업이 필요했나

결제 어댑터 레이어는 외부 PG/결제 수단별 프로바이더를 감싸는 구조인데, 각 프로바이더가 내려주는 응답 포맷이 제각각이다. 이 프로바이더의 응답이 Map<String, Object> 형태로 넘어오는 구조였고, 파싱 코드 여기저기에 키 이름이 리터럴 문자열로 흩뿌려져 있었다.

// Before: 리터럴 문자열이 파싱 로직 곳곳에 산재
String resultCode = (String) responseMap.get("resultCd");
String resultMsg  = (String) responseMap.get("resultMsg");
String authNo     = (String) responseMap.get("authNo");
String tid        = (String) responseMap.get("tradeNo");

이 상태에서 발생하는 문제가 꽤 고전적이다.

• 같은 키 문자열이 여러 메서드에 복붙되면서 오타가 생겨도 컴파일 타임에 잡히지 않음
• 프로바이더 스펙이 바뀌어 키 이름이 변경될 때 전수 검색-수정이 필요함
• 코드 리뷰 시 "이 키가 실제 응답 필드 맞아요?" 라는 질문이 반복적으로 나옴
• 테스트 픽스처 작성할 때도 동일 문자열을 또 써야 해서 테스트 유지보수 비용이 올라감

팀 내에서 이 파일을 건드리는 작업이 종종 발생했고, 매번 "이 키 이름 진짜 맞아요?"를 확인하는 커뮤니케이션 오버헤드가 쌓이고 있었다. 결국 이번에 시간을 내서 정리했다.

작업 내용

WelcomeBrandPayProvider 내부에 상수 클래스(또는 상수 블록)를 두고 응답 Map의 키들을 한 곳으로 모았다.

// After: 내부 상수로 집중 관리
private static final class ResponseKey {
    static final String RESULT_CODE = "resultCd";
    static final String RESULT_MSG  = "resultMsg";
    static final String AUTH_NO     = "authNo";
    static final String TRADE_NO    = "tradeNo";

    private ResponseKey() {}
}

// 파싱 로직
String resultCode = (String) responseMap.get(ResponseKey.RESULT_CODE);
String authNo     = (String) responseMap.get(ResponseKey.AUTH_NO);

변경 범위는 해당 프로바이더 내부 클래스 파일 한 곳이다. stat 가 명시되지 않았지만 파일 범위가 하나인 점으로 보아 핀포인트 수정에 가깝다. 외부 인터페이스나 어댑터 상위 레이어에는 영향이 없고, 동작 변경도 없는 순수 리팩터링이다.

이런 작업을 팀 리딩 관점에서 보면

사실 이 종류의 리팩터링은 "지금 당장 버그를 고치는 게 아니니까" 라는 이유로 계속 밀리기 쉽다. 타입이 딱 맞는 기능 티켓도 없고, QA 검증 포인트도 딱히 없다. 그러면서 기술 부채 리스트에만 조용히 쌓인다.

내가 이걸 이번에 처리한 이유는, 이 프로바이더 파일을 수정하는 다른 작업이 예정되어 있었기 때문이다. 그 작업 전에 정리해 두지 않으면, 또 동일한 리터럴을 추가하는 패턴이 반복될 것이 뻔했다. "보이스카우트 룰(Boy Scout Rule)" — 코드를 처음 발견했을 때보다 조금이라도 깔끔하게 두고 나온다 — 을 팀에서 지속적으로 강조하는 편인데, 이번에 내가 직접 그 예시를 만든 셈이다.

코드 리뷰 관점에서도 이후 이 파일을 건드리는 PR이 올라오면 리뷰어가 키 상수를 보고 "아, 여기 정의된 거 쓰면 되겠다" 라고 바로 피드백할 수 있다. 리터럴이 흩뿌려진 상태에서는 "이 문자열이 기존에 있던 건지, 새로 추가한 건지" 를 일일이 확인해야 하는 부담이 리뷰어에게 전가된다.

규모가 작은 리팩터링이지만, 이런 작업이 쌓여야 코드베이스 전체의 유지보수 난이도가 내려간다. 결제 도메인은 특히 키 이름 하나가 틀려도 조용히 null 이 내려오는 구조라 더욱 꼼꼼하게 관리할 필요가 있다.

끝.

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

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

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