Feature/pg circuitbreaker

apps/commerce-api/src/main/java/com/loopers/config/Resilience4jRetryConfig.java

@@ -0,0 +1,129 @@
+package com.loopers.config;
+
+import io.github.resilience4j.retry.RetryConfig;
+import io.github.resilience4j.retry.RetryRegistry;
+import io.github.resilience4j.core.IntervalFunction;
+import lombok.extern.slf4j.Slf4j;
+import feign.FeignException;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import java.time.Duration;
+import java.util.concurrent.TimeoutException;
+import java.net.SocketTimeoutException;
+
+/**
+ * Resilience4j Retry 설정 커스터마이징.
+ * <p>
+ * 실무 권장 패턴에 따라 메서드별로 다른 Retry 정책을 적용합니다:
+ * </p>
+ * <p>
+ * <b>Retry 정책:</b>
+ * <ul>
+ *   <li><b>결제 요청 API (requestPayment):</b> Retry 없음 (유저 요청 경로 - 빠른 실패)</li>
+ *   <li><b>조회 API (getTransactionsByOrder, getTransaction):</b> Exponential Backoff 적용 (스케줄러 - 안전)</li>
+ * </ul>
+ * </p>
+ * <p>
+ * <b>Exponential Backoff 전략 (조회 API용):</b>
+ * <ul>
+ *   <li><b>초기 대기 시간:</b> 500ms</li>
+ *   <li><b>배수(multiplier):</b> 2 (각 재시도마다 2배씩 증가)</li>
+ *   <li><b>최대 대기 시간:</b> 5초 (너무 길어지지 않도록 제한)</li>
+ *   <li><b>랜덤 jitter:</b> 활성화 (thundering herd 문제 방지)</li>
+ * </ul>
+ * </p>
+ * <p>
+ * <b>재시도 시퀀스 예시 (조회 API):</b>
+ * <ol>
+ *   <li>1차 시도: 즉시 실행</li>
+ *   <li>2차 시도: 500ms 후 (500ms * 2^0)</li>
+ *   <li>3차 시도: 1000ms 후 (500ms * 2^1)</li>
+ * </ol>
+ * </p>
+ * <p>
+ * <b>설계 근거:</b>
+ * <ul>
+ *   <li><b>유저 요청 경로:</b> 긴 Retry는 스레드 점유 비용이 크므로 Retry 없이 빠르게 실패</li>
+ *   <li><b>스케줄러 경로:</b> 비동기/배치 기반이므로 Retry가 안전하게 적용 가능 (Nice-to-Have 요구사항 충족)</li>
+ *   <li><b>Eventually Consistent:</b> 실패 시 주문은 PENDING 상태로 유지되어 스케줄러에서 복구</li>
+ *   <li><b>일시적 오류 복구:</b> 네트워크 일시적 오류나 PG 서버 일시적 장애 시 자동 복구</li>
+ * </ul>
+ * </p>
+ *
+ * @author Loopers
+ * @version 2.0
+ */
+@Slf4j
+@Configuration
+public class Resilience4jRetryConfig {
+
+    /**
+     * PaymentGatewayClient용 Retry 설정을 커스터마이징합니다.
+     * <p>
+     * Exponential Backoff 전략을 적용하여 재시도 간격을 점진적으로 증가시킵니다.
+     * </p>
+     *
+     * @return RetryRegistry (커스터마이징된 설정이 적용됨)
+     */
+    @Bean
+    public RetryRegistry retryRegistry() {
+        RetryRegistry retryRegistry = io.github.resilience4j.retry.RetryRegistry.ofDefaults();
+        // Exponential Backoff 설정
+        // - 초기 대기 시간: 500ms
+        // - 배수: 2 (각 재시도마다 2배씩 증가)
+        // - 최대 대기 시간: 5초
+        // - 랜덤 jitter: 활성화 (thundering herd 문제 방지)
+        IntervalFunction intervalFunction = IntervalFunction
+            .ofExponentialRandomBackoff(
+                Duration.ofMillis(500),  // 초기 대기 시간
+                2.0,                      // 배수 (exponential multiplier)
+                Duration.ofSeconds(5)     // 최대 대기 시간
+            );
+
+        // RetryConfig 커스터마이징
+        RetryConfig retryConfig = RetryConfig.custom()
+            .maxAttempts(3)  // 최대 재시도 횟수 (초기 시도 포함)
+            .intervalFunction(intervalFunction)  // Exponential Backoff 적용
+            .retryOnException(throwable -> {
+                // 일시적 오류만 재시도: 5xx 서버 오류, 타임아웃, 네트워크 오류
+                if (throwable instanceof FeignException feignException) {
+                    int status = feignException.status();
+                    // 5xx 서버 오류만 재시도
+                    if (status >= 500 && status < 600) {
+                        log.debug("재시도 대상 예외: FeignException (status: {})", status);
+                        return true;
+                    }
+                    return false;
+                }
+                if (throwable instanceof SocketTimeoutException ||
+                    throwable instanceof TimeoutException) {
+                    log.debug("재시도 대상 예외: {}", throwable.getClass().getSimpleName());
+                    return true;
+                }
+                return false;
+            })
+            // ignoreExceptions는 사용하지 않음
+            // retryOnException에서 5xx만 재시도하고 4xx는 제외하므로,
+            // 별도로 ignoreExceptions를 설정할 필요가 없음
+            .build();
+
+        // 결제 요청 API: 유저 요청 경로에서 사용되므로 Retry 비활성화 (빠른 실패)
+        // 실패 시 주문은 PENDING 상태로 유지되어 스케줄러에서 복구됨
+        RetryConfig noRetryConfig = RetryConfig.custom()
+            .maxAttempts(1)  // 재시도 없음 (초기 시도만)
+            .build();
+        retryRegistry.addConfiguration("paymentGatewayClient", noRetryConfig);
+
+        // 스케줄러 전용 클라이언트: 비동기/배치 기반으로 Retry 적용
+        // Exponential Backoff 적용하여 일시적 오류 자동 복구
+        retryRegistry.addConfiguration("paymentGatewaySchedulerClient", retryConfig);
+
+        log.info("Resilience4j Retry 설정 완료:");
+        log.info("  - 결제 요청 API (paymentGatewayClient): Retry 없음 (유저 요청 경로 - 빠른 실패)");
+        log.info("  - 조회 API (paymentGatewaySchedulerClient): Exponential Backoff 적용 (스케줄러 - 비동기/배치 기반 Retry)");
+
+        return retryRegistry;
+    }
+}
+

apps/commerce-api/src/main/resources/application.yml

@@ -29,6 +29,87 @@ spring:
     job:
       enabled: false # 스케줄러에서 수동 실행하므로 자동 실행 비활성화
 
+  circuitbreaker:
+    enabled: false # FeignClient 자동 Circuit Breaker 비활성화 (어댑터 레벨에서 pgCircuit 사용)
+  resilience4j:
+    enabled: true # Resilience4j 활성화
+
+resilience4j:
+  circuitbreaker:
+    configs:
+      default:
+        registerHealthIndicator: true
+        slidingWindowSize: 20 # 슬라이딩 윈도우 크기 (Building Resilient Distributed Systems 권장: 20~50)
+        minimumNumberOfCalls: 1 # 최소 호출 횟수 (첫 호출부터 통계 수집하여 메트릭 즉시 노출)
+        permittedNumberOfCallsInHalfOpenState: 3 # Half-Open 상태에서 허용되는 호출 수
+        automaticTransitionFromOpenToHalfOpenEnabled: true # 자동으로 Half-Open으로 전환
+        waitDurationInOpenState: 10s # Open 상태 유지 시간 (10초 후 Half-Open으로 전환)
+        failureRateThreshold: 50 # 실패율 임계값 (50% 이상 실패 시 Open)
+        slowCallRateThreshold: 50 # 느린 호출 비율 임계값 (50% 이상 느리면 Open) - Release It! 권장: 50~70%
+        slowCallDurationThreshold: ${RESILIENCE4J_CIRCUITBREAKER_SCHEDULER_SLOW_CALL_DURATION_THRESHOLD:2s} # 느린 호출 기준 시간 (2초 이상) - Building Resilient Distributed Systems 권장: 2s (환경 변수로 동적 설정 가능)
+        recordExceptions:
+          - feign.FeignException
+          - feign.FeignException$InternalServerError
+          - feign.FeignException$ServiceUnavailable
+          - feign.FeignException$GatewayTimeout
+          - feign.FeignException$BadGateway
+          - java.net.SocketTimeoutException
+          - java.util.concurrent.TimeoutException
+        ignoreExceptions: [] # 모든 예외를 기록 (무시할 예외 없음)
+    instances:
+      pgCircuit:
+        baseConfig: default
+        slidingWindowSize: 20 # Building Resilient Distributed Systems 권장: 20 (과제 권장값)
+        minimumNumberOfCalls: 1 # 첫 호출부터 통계 수집하여 메트릭 즉시 노출
+        waitDurationInOpenState: 10s
+        failureRateThreshold: 50
+        slowCallRateThreshold: 50 # 느린 호출 비율 임계값 (50% 이상 느리면 Open) - Release It! 권장: 50~70%
+        slowCallDurationThreshold: ${RESILIENCE4J_CIRCUITBREAKER_PAYMENT_GATEWAY_SLOW_CALL_DURATION_THRESHOLD:2s} # 느린 호출 기준 시간 (2초 이상) - Building Resilient Distributed Systems 권장: 2s (환경 변수로 동적 설정 가능)
+  retry:
+    configs:
+      default:
+        maxAttempts: 3 # 최대 재시도 횟수 (초기 시도 포함)
+        waitDuration: 500ms # 재시도 대기 시간 (기본값, paymentGatewayClient는 Java Config에서 Exponential Backoff 적용)
+        retryExceptions:
+          # 일시적 오류만 재시도: 5xx 서버 오류, 타임아웃, 네트워크 오류
+          - feign.FeignException$InternalServerError # 500 에러
+          - feign.FeignException$ServiceUnavailable   # 503 에러
+          - feign.FeignException$GatewayTimeout      # 504 에러
+          - java.net.SocketTimeoutException
+          - java.util.concurrent.TimeoutException
+        ignoreExceptions:
+          # 클라이언트 오류(4xx)는 재시도하지 않음: 비즈니스 로직 오류이므로 재시도해도 성공하지 않음
+          - feign.FeignException$BadRequest      # 400 에러
+          - feign.FeignException$Unauthorized    # 401 에러
+          - feign.FeignException$Forbidden       # 403 에러
+          - feign.FeignException$NotFound         # 404 에러
+  timelimiter:
+    configs:
+      default:
+        timeoutDuration: 6s # 타임아웃 시간 (Feign readTimeout과 동일)
+        cancelRunningFuture: true # 실행 중인 Future 취소
+    instances:
+      paymentGatewayClient:
+        baseConfig: default
+        timeoutDuration: 6s
+      paymentGatewaySchedulerClient:
+        baseConfig: default
+        timeoutDuration: 6s
+  bulkhead:
+    configs:
+      default:
+        maxConcurrentCalls: 20 # 동시 호출 최대 수 (Building Resilient Distributed Systems: 격벽 패턴)
+        maxWaitDuration: 5s # 대기 시간 (5초 초과 시 BulkheadFullException 발생)
+    instances:
+      paymentGatewayClient:
+        baseConfig: default
+        maxConcurrentCalls: 20 # PG 호출용 전용 격벽: 동시 호출 최대 20개로 제한
+        maxWaitDuration: 5s
+      paymentGatewaySchedulerClient:
+        baseConfig: default
+        maxConcurrentCalls: 10 # 스케줄러용 격벽: 동시 호출 최대 10개로 제한 (배치 작업이므로 더 보수적)
+        maxWaitDuration: 5s
+
 springdoc:
   use-fqn: true
   swagger-ui: