카카오페이 「MSA 환경에서 네트워크 예외를 잘 다루는 방법」 리뷰 — Unknown을 타입으로 만든 글과, Unknown을 상태로 저장한 프로젝트가 갈리는 지점
엔지니어링 요약
Problem
결제 시스템에서 외부 호출의 결과를 모르는 상황(Unknown)을 어떻게 다루는지는 결제 도메인의 핵심 질문이다. 카카오페이 글은 이것을 Kotlin sealed class와 함수형 조합으로 코드 안에서 풀었고, 이후 만든 ParityPay는 DB 상태와 복구 작업으로 풀었다. 같은 문제를 다른 층에서 푼 두 답을 나란히 놓았다.
Decision
원문의 분류(Success·Failure·Unknown), 1단계·2단계 처리 전략, 멱등 API 조건을 그대로 옮긴 뒤, 각 항목을 이후 ParityPay에서 잰 실험 수치(UNKNOWN 확정 지연, 재시도 증폭 3.00배, 차단기 OPEN 중 결제의 운명)와 대조했다.
Result
분류는 같고, 갈리는 곳은 셋이다. 원문의 1단계 첫 선택지인 '즉시 재요청'을 이후 ParityPay는 금지했고(재시도 3회 = 기관 요청 3.00배, 이중 청구는 기관 멱등 덕에만 안 남), 원문이 다루지 않은 '보내지 않은 요청'(차단기·벌크헤드 거절)은 Unknown이 아니라 Failure여야 했으며, 원문의 2단계 '알 수 없는 상태로 저장'이 끝이 아니라 그 다음(확정 지연 45초, 적체 시 초당 10건 상한, 클라이언트의 폴링 계약)이 실험에서 나온 결함의 절반이었다.
원문: MSA 환경에서 네트워크 예외를 잘 다루는 방법 — 카카오페이 기술 블로그, larry(Payment Clan), 2022-05-25
이 글을 고른 이유는 “결과를 모르는 외부 호출을 실무 결제 팀은 어떻게 푸는가”가 궁금했기 때문이다. 카카오페이 글은 2022년 글이고, 결제 도메인에서 네트워크 예외를 세 가지 결과로 나누는 것부터 시작한다. 이후 만든 ParityPay도 같은 세 가지에서 시작했고, 3편을 쓴 뒤 이 글에 대조를 덧붙였다. 그래서 요약보다 대조가 의미 있다.
원문이 말하는 것
원문은 페이상품권 서버를 개발하는 저자가 쓴 글이다. 마이크로서비스 간 호출에서 생길 수 있는 예외 상황을 고객 입장(두 번 결제, 취소 실패, 잔액이 잘못 돌아옴 등)과 서버 입장으로 나누고, 저자가 주관적으로 매긴 “매운맛”을 붙인다. 가장 매운 세 개는 서버 입장의 “결제가 실패했는지 성공했는지 알 수 없을 때”에 붙어 있다. 원문이 든 예는 실패로 간주한 경우다. 결제 서버는 잔액을 차감했는데 주문 서버가 타임아웃을 실패로 저장하면, 고객은 돈이 빠져나갔는데 주문은 실패한 상태가 된다. 그래서 요청의 결과를 Success, Failure, 그리고 결과를 알 수 없는 Unknown 셋으로 나누고 상태마다 처리를 따로 둔다.
Unknown의 처리는 두 단계로 읽힌다(단계 이름은 내가 붙였다). 1단계 후보로 원문은 여섯 가지를 든다. 즉시 재요청, 일정 시간 뒤 재시도, 성공했는지 확인 후 재시도, 결제 취소 요청(보상 트랜잭션), 무조건 성공 후 뒤처리, 수기 처리다. 후처리도 API 요청이라 다시 Unknown이 날 수 있으므로, 상품권 도메인은 고객 응답이 나가기 전까지만 후처리를 시도한다. 그것도 실패하면 2단계로 “알 수 없는 상태”로 저장하고 사용자에게 재시도 안내와 함께 응답한다. 사용자가 다시 시도하면 후처리를 이어 가고, 그마저 실패하면 다른 장치로 데이터를 보정한다고 적었다. 이 전략이 성립하려면 하위 API가 멱등해야(같은 요청을 여러 번 보내도 같은 응답) 하므로, 요청에 고유한 tx_key를 실어 재요청과 새 요청을 구분한다.
구현은 Kotlin sealed class ActResult<A>로 세 결과를 타입으로 만들고(sealed class는 직접 하위 클래스가 컴파일 시점에 모두 알려진다는 것이 Kotlin 문서의 설명이다), map·flatMap·recoverUnknown·onSuccess·onFailure·onUnknown으로 결제 흐름을 조합한다. 검증 → 결제 어댑터 호출 → Unknown이면 한 번 더 호출 → 결과별 마킹이 한 체인으로 읽힌다. 깊어지는 try-catch를 리팩터링하다 의도치 않은 롤백이 생기는 것을 피하는 것이 코드 쪽 동기다. 글 전체의 전제는 도입부에 있다. 모놀리식 구조라 해도 무조건적인 롤백은 지양하고 도메인 환경에 맞는 트랜잭션 관리를 해야 한다는 것이다.
같은 곳
분류가 같다. 이후 ParityPay는 외부 승인 결과를 성공·실패·UNKNOWN으로 나누고, 타임아웃을 실패로 확정하지 않는 것을 ADR-007의 첫 규칙으로 뒀다. “Unknown이 가장 위험하다”는 판단도 같다. 원문이 매운맛 세 개로 표시한 그 자리를 ParityPay는 불변조건 INV-004(“같은 업무 참조의 금융 효과는 한 번만”)로 표시했다.
멱등 키의 역할도 같다. 원문의 tx_key가 ParityPay의 멱등 키와 외부 키(결제 ID)다. 재요청과 새 요청을 구분하는 것은 우리 쪽 키가 하고, 하위 기관이 그 키를 존중하는지는 기관에 달려 있다. 2021년의 결제대행 연동에서 그 키가 있었는지조차 기억나지 않는다고 적었는데, 원문은 2022년에 이미 그것을 전제로 쓰고 있다.
갈리는 곳 1: “즉시 재요청”을 첫 선택지로 둘 수 있는가
원문의 1단계 첫 항목은 즉시 재요청이고, 코드에서도 recoverUnknown { paymentAdapter.pay(request) }로 Unknown이면 한 번 더 보낸다. 하위 API가 멱등하다는 전제 위에서는 맞는 선택이다.
나중에 ParityPay에서는 이 선택지를 금지했다. 승인 요청을 재전송하지 않고 상태 조회를 우선한다. 이유는 이후 9편의 재시도 실험에서 나왔다. 타임아웃 3초에 재시도 3회를 붙이자 기관이 받은 요청이 정확히 3.00배가 됐고, 그 기관은 이미 느려서 타임아웃이 나던 중이었다. 이중 청구가 안 난 것은 Mock PG가 외부 키로 멱등했기 때문이고, 그 멱등성이 없는 기관이면 승인 기록 903건, 한 결제에 세 번 청구였다. 원문의 전제(하위 API가 멱등하다)가 성립하면 즉시 재요청은 안전하지만, 그 전제를 우리가 검증할 수 없는 외부 기관에 대해서는 재요청보다 조회가 안전하다는 것이 ParityPay의 판단이다. 원문의 세 번째 선택지 “요청이 성공했는지 확인 후 재시도”가 ParityPay의 유일한 선택지다.
이것은 원문이 틀렸다는 뜻이 아니다. 원문의 대상은 카카오페이 안의 마이크로서비스 간 호출이고, 원문은 결제 서버가 멱등성을 제공하는 쪽으로 설명한다. 나는 이것을 같은 조직이 멱등 API를 만들고 보증하는 구조로 읽는다. ParityPay의 대상은 외부 기관이다. 그래서 재요청을 첫 선택지로 둘 수 있는지는 하위 API의 멱등성을 누가 보증하는가로 갈린다.
갈리는 곳 2: 보내지 않은 요청은 Unknown인가
원문의 Unknown은 “보냈는데 결과를 모름”이다. 타임아웃이 대표다. 그런데 결제 서버에는 요청을 보내지 않은 실패도 있다. 차단기가 OPEN이라 거절했거나, 벌크헤드가 찼거나, 리미터에 걸린 경우다. 원문은 이 경우를 다루지 않는다. 2022년 글이고 주제가 네트워크 예외이므로 당연하다.
이후 ParityPay에서 이 구분이 실험으로 강제됐다. 9편에서 차단기를 붙이자 OPEN 동안 들어온 결제 329~360건이 거절됐는데, 이것을 UNKNOWN으로 두면 복구 작업이 존재하지 않는 기록을 기관에 묻는다. 그래서 PgCallRejectedException으로 구분해 FAILED(CIRCUIT_OPEN)으로 확정했고, 결제 ID로 대조해 기관 도달 0건을 확인했다. 원문의 ActResult로 표현하면 Failure이지 Unknown이 아니다. 그래서 Unknown의 정의는 “결과를 모름”이 아니라 “보냈는데 결과를 모름”이어야 한다. 그 차이가 복구 작업의 부하와 사용자가 다시 시도할 수 있는지를 가른다. 원문의 타입 설계에 이 구분을 넣는다면 Rejected가 하나 더 필요하다.
갈리는 곳 3: 2단계 “알 수 없는 상태로 저장” 다음에 무엇이 있는가
원문의 2단계는 Unknown을 저장하고 사용자에게 재시도를 안내한다. 사용자가 다시 시도하면 후처리를 이어 가고, 그것도 실패하면 다른 장치로 보정한다. 그 장치가 무엇인지는 원문에 없다. 글의 범위로는 맞는 끝이다.
이후 ParityPay에서는 그 다음이 실험의 절반이었다. UNKNOWN으로 저장한 뒤 복구 작업이 확정하기까지 얼마나 걸리는가(3편: 확정 지연은 상수였고 프론트엔드가 틀린 값을 갖고 있었다), 미확정이 1,000건 쌓이면 어떻게 되는가(결함 K: 복구 작업이 틱당 한 배치라 초당 10건 상한, 45%가 클라이언트의 90초 안에 답을 못 받음), 취소의 UNKNOWN은 HTTP 계약에 있는가(결함 L: 201로 나가고 조회 API가 없어 화면이 “취소됨”으로 보여줌). “알 수 없는 상태로 저장”은 문장 하나지만, 그 상태를 얼마나 빨리, 어떤 API로, 어떤 순서로 확정하는지가 설계의 나머지 절반이다. 원문이 “사용자 재시도”에 후처리를 맡긴 것과 ParityPay가 배경 복구 작업에 맡긴 것도 다른 선택이다. 전자는 사용자가 돌아오지 않으면 원문이 밝히지 않은 보정 장치에 기대야 하고, 후자는 사용자가 없어도 수렴하지만 작업의 처리량이 곧 확정 속도다.
원문이 잘한 것
Unknown을 예외(catch)가 아니라 값으로 만든 것이다. 예외로 두면 어디서 잡느냐에 따라 롤백 범위가 달라지고, 원문이 지적한 “리팩터링이 의도치 않은 롤백을 만든다”는 문제가 그것이다. 값으로 만들면 Unknown이 체인을 따라 끝까지 전달되고, 마지막에 onUnknown이 반드시 호출된다. Kotlin 문서는 sealed class를 when과 함께 쓰면 컴파일러가 모든 경우를 다뤘는지 검사한다고 설명한다. 내가 보기에 이 검사가 “Unknown을 빠뜨리지 않는다”를 코드 수준에서 보장하는 장치다. 나중에 ParityPay는 이 문제를 DB 상태(UNKNOWN 행)로 풀었는데, 그것은 프로세스가 죽어도 남는다는 장점이 있지만 코드 안에서의 흐름은 원문만큼 읽기 쉽지 않다. 두 층은 배타적이지 않다. 코드 안에서는 값으로, 코드 밖에서는 상태로 두는 것이 맞고, ParityPay에 원문의 ActResult 같은 타입이 있었다면 3편의 “설계 문서에 없던 경로”(외부 호출 직전 중단으로 PROCESSING에 갇히는 거래)를 컴파일 시점에 더 일찍 봤을 가능성이 있다.
가져갈 것
- Unknown은 예외가 아니라 값이다. 체인의 끝까지 전달되고 반드시 처리된다.
- 즉시 재요청이 안전한지는 하위 API의 멱등성을 누가 보증하는가로 정한다. 같은 조직이면 재요청, 외부 기관이면 조회.
- 보내지 않은 요청은 Unknown이 아니다.
Rejected를 따로 둔다. - “알 수 없는 상태로 저장”은 시작이다. 확정 지연, 적체 처리량, HTTP 계약이 그 다음이고, 실험 없이는 보이지 않는다.
댓글
아직 댓글이 없습니다