[Week6] 외부시스템 장애 대응 Resilience 설계

[wiggleji]

💻 Implementation Quest

외부 시스템(PG) 장애 및 지연에 대응하는 Resilience 설계를 학습하고 적용해봅니다.
pg-simulator 모듈을 활용하여 다양한 비동기 시스템과의 연동 및 실패 시나리오를 구현, 점검합니다.

🎯

**Must-Have (이번 주에 무조건 가져가야 좋을 것-**무조건 하세요)

• Fallback
• Timeout
• CircuitBreaker

**Nice-To-Have (부가적으로 가져가면 좋을 것-**시간이 ****허락하면 ****꼭 해보세요)

• Retryer

🤖 나의 시니어 파트너

• 외부 시스템과 연동되는 기능 설계를 분석하고, 개발자와의 질의응답을 통해 구조를 명확히 하며, 상태 불일치·트랜잭션 경계·장애 시나리오 관점에서 리스크를 드러낼 수 있는 Skills 를 작성해봅니다.

  작성 예시 ( ~/.claude/skills/anylize-external-integration/SKILL.md )

  ---
  name: analyze-external-integration
  description:
    외부 시스템(결제, 재고 시스템, 메시징, 서드파티 API 등)과 연동되는 기능의 설계를 분석한다.
    트랜잭션 경계, 상태 일관성, 실패 시나리오, 재시도 및 중복 실행 가능성을 중심으로 리스크를 드러낸다.
    설계를 대신 생성하지 않으며, 이미 작성된 설계를 검증하고 개선 선택지를 제시하는 데 사용한다.
    외부 시스템 호출이 포함된 기능 구현 전/후 설계 리뷰 목적으로 사용한다.
  ---
  
  외부 시스템 연동 설계를 분석할 때 반드시 다음 흐름을 따른다.
  
  ### 1️⃣ 기능이 아니라 "불확실성" 관점으로 재해석한다
  - 단순 호출 순서를 요약하지 않는다.
  - 외부 시스템은 항상 다음을 만족한다고 가정한다:
    - 지연될 수 있다
    - 실패할 수 있다
    - 중복 실행될 수 있다
    - 성공했지만 응답이 유실될 수 있다
  - 현재 설계가 이러한 불확실성을 어떻게 다루는지 설명한다.
  
  ---
  
  ### 2️⃣ 트랜잭션 경계를 검증한다
  - 외부 호출이 트랜잭션 내부에 존재하는지 확인한다.
  - 외부 시스템과 내부 DB 상태가 하나의 트랜잭션처럼 다뤄지고 있는지 분석한다.
  - 다음 질문을 반드시 포함한다:
    - 외부 호출 실패 시 내부 상태는 어떻게 되는가?
    - 내부 커밋 이후 외부 호출 실패 시 복구 가능한가?
    - 외부 성공 후 내부 실패 시 상태는 어떻게 정합성을 유지하는가?
  
  ---
  
  ### 3️⃣ 상태 기반으로 구조를 다시 본다
  - 호출 흐름이 아니라 상태 전이를 중심으로 설명한다.
  - 내부 도메인 상태와 외부 시스템 상태를 분리해서 정리한다.
  - 두 상태가 어긋날 수 있는 지점을 명시한다.
  
  ---
  
  ### 4️⃣ 중복 요청 및 재시도 가능성을 분석한다
  - 네트워크 재시도 상황을 가정한다.
  - 동일 요청이 두 번 실행될 경우 문제를 설명한다.
  - 멱등성(Idempotency) 고려 여부를 확인한다.
  
  ---
  
  ### 5️⃣ 장애 시나리오를 최소 3가지 이상 생성한다
  - 정상 흐름보다 실패 흐름을 우선한다.
  - 각 장애 상황에서:
    - 데이터 정합성
    - 상태 불일치
    - 복구 가능성
    을 분석한다.
  
  ---
  
  ### 6️⃣ 해결책은 정답처럼 제시하지 않는다
  - 현재 구조의 장점과 리스크를 분리한다.
  - 대안 구조가 있다면 선택지 형태로 제시한다.
    예:
    - 동기 호출 유지
    - 상태 기반 단계 분리
    - 비동기 이벤트 전환
  - 각 선택지의 복잡도와 운영 부담을 함께 설명한다.
  
  ---
  
  ### 7️⃣ 톤 & 스타일 가이드
  - 코드 레벨 수정안을 직접 제시하지 않는다.
  - 설계를 비판하지 말고 리스크를 드러내는 리뷰 톤을 유지한다.
  - 외부 시스템은 항상 신뢰할 수 없다는 전제를 유지한다.
  - 구현보다 책임, 경계, 상태 일관성을 중심으로 분석한다.
  

외부 시스템과 연동되는 기능 설계를 분석하고,
개발자와의 질의응답을 통해 구조를 명확히 하며,
상태 불일치·트랜잭션 경계·장애 시나리오 관점에서 리스크를 드러낼 수 있는 Skills 를 작성해봅니다.

외부 시스템과 연동되는 기능 설계를 분석하고,
개발자와의 질의응답을 통해 구조를 명확히 하며,
상태 불일치·트랜잭션 경계·장애 시나리오 관점에서 리스크를 드러낼 수 있는 Skills 를 작성해봅니다.

📦 결제 기능 추가

• 주문에 대한 결제 기능을 추가합니다.
• 주문항목과 결제 수단을 입력받아, 외부 결제 시스템과 연동 후 주문에 대한 결제 처리를 하는 API 를 작성합니다.

## commerce-api
POST {{commerce-api}}/api/v1/payments
X-Loopers-LoginId: 
X-Loopers-LoginPw:
Content-Type: application/json

{
  "orderId": "1351039135",
  "cardType": "SAMSUNG",
  "cardNo": "1234-5678-9814-1451",
}

💰 결제 시스템 연동

## PG-Simulator
### 결제 요청
POST {{pg-simulator}}/api/v1/payments
X-USER-ID: 
Content-Type: application/json

{
  "orderId": "1351039135",
  "cardType": "SAMSUNG",
  "cardNo": "1234-5678-9814-1451",
  "amount" : "5000",
  "callbackUrl": "http://localhost:8080/api/v1/examples/callback"
}

### 결제 정보 확인
GET {{pg-simulator}}/api/v1/payments/20250816:TR:9577c5
X-USER-ID: 

### 주문에 엮인 결제 정보 조회
GET {{pg-simulator}}/api/v1/payments?orderId=1351039135
X-USER-ID: 

• PG 기반 카드 결제 기능을 추가합니다.
• PG 시스템은 로컬에서 실행가능한 pg-simulator 모듈이 제공됩니다. ( 별도 SpringBootApp )
• PG 시스템은 비동기 결제 기능을 제공합니다.

비동기 결제란, 요청과 실제 처리가 분리되어 있음을 의미합니다.
요청 성공 확률 : 60%
요청 지연 : 100ms ~ 500ms
처리 지연 : 1s ~ 5s
처리 결과

• 성공 : 70%
• 한도 초과 : 20%
• 잘못된 카드 : 10%

• java

[GitHub - Loopers-dev-lab/loopback-be-l2-java-additionals: 루프팩 BE L2 수강생들을 위한 추가사항](https://github.com/Loopers-dev-lab/loopback-be-l2-java-additionals)

• kotlin

[6주차 과제 / pg-simulator 모듈 추가 by hubtwork · Pull Request #1 · Loopers-dev-lab/loopback-be-l2-kotlin-additionals](Loopers-dev-lab/loopback-be-l2-kotlin-additionals#1)

📋 과제 정보

• 외부 시스템에 대해 적절한 타임아웃 기준에 대해 고려해보고, 적용합니다.
• 외부 시스템의 응답 지연 및 실패에 대해서 대처할 방법에 대해 고민해 봅니다.
• PG 결제 결과를 적절하게 시스템과 연동하고 이를 기반으로 주문 상태를 안전하게 처리할 방법에 대해 고민해 봅니다.
• 서킷브레이커를 통해 외부 시스템의 지연, 실패에 대해 대응하여 서비스 전체가 무너지지 않도록 보호합니다.

---

✅ Checklist

⚡ PG 연동 대응

• PG 연동 API는 RestTemplate 혹은 FeignClient 로 외부 시스템을 호출한다.
• 응답 지연에 대해 타임아웃을 설정하고, 실패 시 적절한 예외 처리 로직을 구현한다.
• 결제 요청에 대한 실패 응답에 대해 적절한 시스템 연동을 진행한다.
• 콜백 방식 + 결제 상태 확인 API를 활용해 적절하게 시스템과 결제정보를 연동한다.

🛡 Resilience 설계

• 서킷 브레이커 혹은 재시도 정책을 적용하여 장애 확산을 방지한다.
• 외부 시스템 장애 시에도 내부 시스템은 정상적으로 응답하도록 보호한다.
• 콜백이 오지 않더라도, 일정 주기 혹은 수동 API 호출로 상태를 복구할 수 있다.
• PG 에 대한 요청이 타임아웃에 의해 실패되더라도 해당 결제건에 대한 정보를 확인하여 정상적으로 시스템에 반영한다.