결제 어댑터 정적 검증으로 예외·결과 객체 품질 개선과 쇼핑몰 플랫폼 제외

Codex 정적 검증을 돌렸더니 payment-adapter 레이어에서 몇 가지 이슈가 한꺼번에 터졌다. 동시에 쇼핑몰 플랫폼 어댑터를 아예 제외하는 범위 결정도 이번 커밋에 같이 묶였다.

배경: 왜 Codex 검증을 이 시점에 돌렸나

결제 어댑터 레이어는 구조적으로 민감한 영역이다. 외부 PG와 직접 맞닿는 경계선이고, 예외 흐름이나 결과 객체가 조금만 어긋나도 정산 오류나 상태 불일치로 이어질 수 있다. 그래서 구현이 어느 정도 안정됐다고 판단하는 시점에 Codex를 돌려서 코드 품질을 한 번 훑는 루틴을 넣어뒀다.

이번에 검증을 트리거한 건 provider 쪽 어댑터 추가 작업이 마무리된 직후였다. 새 코드가 붙으면 기존 인터페이스와의 정합성 문제가 숨어있을 가능성이 높아지기 때문에, 타이밍상 지금이 맞다고 봤다.

무엇이 발견됐나

변경된 파일을 보면 크게 세 축이다.

PaymentException과 PaymentResult는 어댑터 레이어의 핵심 계약(contract)이다. 이 두 클래스가 흔들리면 상위 서비스 레이어까지 연쇄로 영향이 간다. Codex가 이 지점에서 뭔가를 잡아냈다는 건, 예외 처리 누락이든 필드 일관성 문제든 간에 방치하면 운영에서 잡기 어려운 유형이었을 가능성이 높다.

// PaymentResult 류 결과 객체에서 흔히 발생하는 패턴 이슈 예시
// AS-IS: nullable 필드를 검사 없이 바로 참조
public String getErrorCode() {
    return this.errorDetail.getCode(); // errorDetail null 가능성
}

// TO-BE: 방어적 처리 + 명확한 상태 표현
public String getErrorCode() {
    return this.errorDetail != null ? this.errorDetail.getCode() : null;
}

실제 코드가 정확히 이 패턴이었다는 건 아니고, Codex가 이런 류의 null 안전성이나 예외 전파 누락을 잡아내는 경우가 많다는 맥락에서 예시로 든 것이다.

쇼핑몰 플랫폼 어댑터 제외 — 범위 결정

이번 커밋에서 기술적으로 더 중요한 결정은 쇼핑몰 플랫폼 어댑터를 provider 목록에서 제외한 것이다. 이런 제외 결정은 단순한 코드 삭제가 아니다.

• 왜 제외하는가: 해당 플랫폼이 현재 서비스 범위 밖으로 정리됐거나, 인터페이스 스펙이 현재 어댑터 추상화와 맞지 않아서 따로 떼어내야 하는 상황
• 제외 vs 비활성화: 코드를 살려두고 feature flag로 끄는 방법과, 아예 provider 목록에서 빼는 방법 중 후자를 택했다는 건 당분간 재진입 계획이 없거나, 코드 유지 비용이 더 크다고 판단했다는 의미
• 팀 공유 포인트: 이런 제외 결정은 반드시 커밋 메시지나 PR에 이유를 명시해야 한다. 나중에 "왜 없어졌지?" 하고 git blame 파는 사람이 반드시 생긴다

provider 디렉터리에 내부 클래스 두 개가 동시에 변경된 걸 보면, 하나는 제외된 쇼핑몰 플랫폼 어댑터이고 하나는 그 영향을 받은 공통 provider 베이스거나 팩토리 쪽일 가능성이 있다. sysconfig 웹 레이어까지 수정된 건, 어댑터 목록이 설정 화면에 노출되는 구조라면 자연스러운 연쇄다.

회고

Codex 검증 → 이슈 수정 → 범위 결정이 한 커밋에 묶인 건 솔직히 이상적이지는 않다. 검증 이슈 수정과 어댑터 제외는 목적이 다른 변경이라 분리했으면 리뷰하기 더 편했을 것이다. 다만 실무에서는 작업 흐름상 한 맥락에서 발견된 것들을 한 번에 처리하는 경우가 생긴다. 그게 나쁜 건 아닌데, 커밋 메시지를 조금 더 쪼개서 설명해줬으면 나중에 추적이 더 수월했겠다 싶다.

payment-adapter는 특성상 팀원들이 건드리기 무서워하는 영역 중 하나다. Codex 같은 자동화 도구를 주기적으로 돌리는 게 이런 레이어의 품질을 유지하는 현실적인 방법이고, 이번처럼 새 코드가 붙는 시점에 트리거하는 습관은 계속 가져가려 한다.

끝.

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

• 결제 시스템 모니터링 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

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