결제 워커의 공통 클라이언트와 변경 전파

결제 승인과 취소, 저장결제 등록·삭제를 처리하는 워커는 각각 별도 서비스였습니다. 비슷한 벤더 API를 호출하면서도 헤더와 요청 조립, 오류 처리와 로그가 서비스마다 조금씩 달랐습니다.

버그 하나를 고칠 때 같은 수정을 여러 서비스에 반복해야 했고, 한 곳이 빠지면 동작이 다시 달라졌습니다. 글로벌 팀과 협의한 뒤 공통 클라이언트를 직접 개발하고 워커에 적용하는 방향으로 정리했습니다.

글로벌 공통 코드와 로컬 연동

한국의 결제 기능을 추가할 때는 벤더의 인증과 응답 차이를 어디에서 처리할지 먼저 봐야 했습니다. 공통 결제 모델이나 처리 규칙을 바꾸면 그 코드를 사용하는 다른 결제 흐름에도 영향이 갈 수 있기 때문입니다.

벤더별 API 차이는 로컬 연동 계층에서 처리하고, 여러 서비스가 함께 사용할 규칙은 공통 라이브러리로 관리했습니다. 공통 코드가 바뀐다고 모든 서비스의 실행 중인 코드가 즉시 바뀌는 것은 아닙니다. 어떤 버전이 각 서비스의 빌드와 배포에 들어갔는지 확인해야 실제 영향 범위를 알 수 있습니다.

서비스 재구축과 클라이언트 공통화

카카오페이 v2는 서비스 자체의 모델과 검증, 저장·로그 규칙을 다시 구성한 작업이었습니다. 이후의 공통 클라이언트는 여러 워커가 벤더를 호출하는 코드를 묶는 별도 작업이었습니다.

2023년 말에는 카카오페이 클라이언트부터 만들며 라이브러리의 기본 구조를 잡았습니다. 이후 네이버페이와 KPN·Fiserv 관련 클라이언트로 범위를 넓혔고, 2024년 봄까지 워커 적용과 운영 기능 연동을 이어 갔습니다.

처음부터 모든 벤더의 모든 동작을 같은 형태로 만들 수는 없었습니다. 공통 인터페이스와 에러 처리 기준을 정하되, 등록 상태 확인이나 벤더별 필수값은 각 구현체에서 처리해야 했습니다.

공통 규칙의 범위

인증 정보와 헤더 구성, 공통 요청 조립, 로깅과 에러 분류처럼 반복되는 부분을 묶었습니다. 승인이나 취소를 재시도해도 되는 조건은 업무별로 달랐기 때문에, 모든 호출에 같은 재시도 횟수를 붙이는 방식으로 처리할 수는 없었습니다.

특히 요청이 타임아웃됐더라도 상대 시스템에서 결제가 처리됐을 수 있습니다. 결과 조회나 중복 방지 기준을 확인하지 않고 다시 승인 요청을 보내면 안 됩니다. 공통화할 때도 이런 차이를 표현할 수 있어야 했습니다.

로그·메시지·감사 기록의 연결

운영에서는 하나의 결제 처리와 관련된 로그, SQS 메시지, audit DB 기록을 함께 찾아야 했습니다. 공통 클라이언트를 정리하면서 traceId를 기준으로 흐름을 연결하고, 예외와 로그 필드도 같은 기준으로 맞췄습니다.

같은 traceId가 있다고 모든 비동기 처리가 자동으로 연결되는 것은 아닙니다. 메시지로 전달하고 수신 시 다시 연결하는 처리가 필요하며, 재시도·재처리 기록도 구분할 수 있어야 합니다. 스레드를 재사용하는 환경에서는 이전 요청의 MDC가 남지 않게 정리해야 합니다.

이후 공통 로깅 플래그를 클라이언트에도 연결했습니다. 해당 기능의 서비스별 반영은 로깅 플래그 전파에서 설명합니다.

워커별 적용과 버전 확인

라이브러리를 배포한 뒤에는 사용하는 서비스에도 새 버전을 적용해야 했습니다. 각 워커의 의존 버전과 실제 배포를 확인하고, 사용하는 승인·취소·등록 경로가 유지되는지 검증해야 했습니다.

공통 인증 라이브러리의 버전도 함께 맞췄습니다. 의존성을 통일했다고 모든 호환성이 보장되는 것은 아니므로, 서비스의 전체 의존 관계와 호출 결과를 확인해야 했습니다.

이렇게 클라이언트의 공통 부분을 모았지만 서비스별 수정은 계속 필요했습니다. 이어지는 글에서는 네이버페이 연동의 동시성 파싱 문제를 다룹니다.