Cloud OpenFeign 의 재시도는 언제 동작할까? Retryer.Default 동작 원리와 테스트

README

WireMock에 대한 설명이 부족하며, WireMock을 알고 있는 가정 하에 진행됩니다.

WireMock에 대한 설명은 아래를 참고해주세요.

- Spring Cloud Contract WireMock Docs
- Baeldung 의 Introduction WireMock
- 우아한기술블로그 : 야, 너두 WireMock 으로 테스트할 수 있어

 
Cloud OpenFeign 에 재시도를 위해 Retryer.Default 를 빈으로 등록했을 때 아래 2가지 경우 시 재시도를 하는 것을 확인하고 테스트 하는 과정을 소개합니다.
1. IOException 발생 시, 재시도
2. 응답에 Retry-After 헤더가 있어서 RetryableException이 발생할 때, 재시도
 

서론: Feign vs OpenFeign의 재시도 차이

Feign 의 재시도 조건

1. IOException 발생 시, 일시적인 네트워크 오류로 간주해 재시도를 합니다.
2. 응답에 Retry-After 헤더가 있을 경우 재시도를 합니다.
 

Cloud OpenFeign 의 재시도 조건

하지만, Cloud OpenFeign 은 별도의 Feign.Retryer 빈을 등록하지 않으면 재시도를 하지 않습니다. 기본 설정은 Retryer.NEVER_RETRY 를 사용하기 때문입니다.

A bean of Retryer.NEVER_RETRY with the type Retryer is created by default, which will disable retrying.
Notice this retrying behavior is different from the Feign default one, where it will automatically retry IOExceptions, treating them as transient network related exceptions, and any RetryableException thrown from an ErrorDecoder.

 
그래서, OpenFeign에서 재시도를 사용하려면 Feign 의 Retryer 빈을 재정의해야 합니다.
예를 들어, 아래 코드는 모든 @FeignClient에 재시도를 추가하는 전역적인 설정 클래스입니다.

@Configuration // 해당 어노테이션이 있으면 모든 @FeignClient 에 전역적 설정
@EnableFeignClients
public class GlobalFeignClientConfig {

    /**
     * 0.1초의 간격으로 시작해 최대 1초의 간격으로 점점 증가하며, 최대 5번 재시도한다.
     */
    @Bean
    Retryer.Default retryer() {
        return new Retryer.Default(100L, TimeUnit.SECONDS.toMillis(1L), 5);
    }
}

@FeignClient(name =, url=)
public interface GithubClient {

    @GetMapping(path = "...", headers = "...")
    List<DockerImage> getAllDockerImages();
}

 
그렇다면 재정의한 Retryer가 IOException 과 RetryableException 이 발생했을 때 재시도를 하는지 테스트를 해보려고 합니다.
 

Mock이 아닌 WireMock을 사용해야 하는 이유

Mock의 한계

@FeignClient의 재시도 로직을 테스트하려면 @Mock이나 @MockBean을 사용할 수 없습니다.
@FeignClient 자체를 모킹하면 아래와 같은 다양한 컴포넌트들이 동작하지 않게 됩니다.

• Retryer - 재시도 담당
• ErrorDecoder - 200번대 외 응답 처리
• Encoder/Decoder - 직렬화/역직렬화

	@Autowired FeignClient	@Mock / @MockBean FeignClient
생성 방식	Spring이 동적 프록시 생성	Mockito가 가짜 객체 생성
내부 컴포넌트	Retryer, ErrorDecoder 등 실제 동작	모든 내부 로직 무시
메서드 호출 시	실제 HTTP 통신 + Feign 파이프라인 실행	Mockito 설정된 동작만 반환 (기본: null)

따라서 Feign Client의 재시도 로직을 제대로 테스트하려면 실제 FeignClient 빈을 주입받아야 합니다.
 

실제 FeignClient 프록시 확인하기

@Autowired로 FeignClient를 주입받고 디버깅해보면 프록시 객체 내부에 Retryer가 설정되어 있는 것을 확인할 수 있습니다.

@Autowired
private GithubClient githubClient;

@Test
void test() {
    System.out.println(githubClient.getClass().getSimpleName());  // <-- 브레이킹 포인트
}

 
디버거 결과

Retryer 가 적용된 모습

 

WireMock으로 HTTP 서버 모킹하기

실제 FeignClient를 테스트하려면 HTTP 요청을 받을 서버가 필요합니다. 이때 WireMock을 사용하여 HTTP 서버를 모킹할 수 있습니다.
 
의존성을 추가합니다.

testImplementation 'org.springframework.cloud:spring-cloud-contract-wiremock'

 
 

Retryer.Default 의 재시도 조건 자세히 알아보기

이번 내용은 Feign 의 재시도 조건인 IOException 과 Retry-After 헤더가 있을 때, 정말 재시도를 하는지 내부 코드를 보며 확인하는 내용입니다.

재시도 조건 1. IOException 발생

Retryer.Default의 코드를 확인하면 RetryableException이 발생했을 때 재시도하는 것을 알 수 있습니다.

Retryer.Default() 정책

 
그렇다면 RetryableException 은 언제 만들어질까요?
 
Feign의 SynchronousMethodHandler.executeAndDecode( ) 메서드를 살펴보면 RetryableException이 어떻게 생성되는지 알 수 있습니다.
 
executeAndDecode 에서  RetryableException 이 만들어지니, executeAndDecode 로 들어가봅니다.

 
client.execute에서 IOException이 발생하면 errorExecuting() 메서드가 호출되고, 이 메서드가 RetryableException을 생성합니다.

 
정리하면, 요청 중 IOException 발생 → RetryableException 생성 → Retryer.Default가 재시도
 

재시도 조건 2. Retry-After 헤더가 있을 때, 재시도를 합니다.

두 번째경우는 ErrorDecoder 에서 Retry-After 란 헤더를 파싱해서, 해당 헤더가 있으면 new RetrableException 을 발생하는데요.

 
Retry-After 헤더는 서버가 클라이언트에게 "잠시 후에 다시 시도해달라"고 알려주는 HTTP 헤더입니다.
주로 다음과 같은 상태 코드와 함께 사용됩니다.

• 503 Service Unavailable - 서비스 일시적 중단
• 429 Too Many Requests - 요청 제한 초과
  • 참고 : https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After

HTTP/1.1 429 Too Many Requests
Retry-After: 60

--> "60초 후에 다시 시도해주세요"

 

Retry-After vs 설정값, 어떤 게 우선일까?

Retryer.Default를 생성할 때 최대 대기 시간(maxPeriod)을 설정했는데, Retry-After 헤더 값과 충돌하면 어떻게 될까요?

new Retryer.Default(100L, TimeUnit.SECONDS.toMillis(1L), 5);
//                          ↑ maxPeriod = 1초

 
이 역시, Retryer.Default 의 내부 로직을 보면 알 수 있습니다.
 
Retry-After 헤더 값이 우선이지만, 사용자가 설정한 maxPeriod를 초과할 수는 없습니다.

public void continueOrPropagate(RetryableException e) {
    long interval;
    if (e.retryAfter() != null) {
        // Retry-After 값이 있으면 우선 사용
        interval = e.retryAfter() - currentTimeMillis();
        if (interval > maxPeriod) {
            interval = maxPeriod;  // 단, maxPeriod를 초과하면 제한
        }
    } else {
        // Retry-After 없으면 설정값 사용
        interval = nextMaxInterval();
    }
}

 
그래서, 서버가 응답한 Retry-After 헤더의 값을 엄격하게 지키고 싶다면, Retryer 의 continueOrPropagate( ) 를 오버라이딩해야 합니다.

Retryer.Default() 정책

 

테스트 코드 작성하기

테스트할 내용은 다음 2가지입니다.
1. IOException 발생 시 재시도가 되는지?
2. Retry-After 헤더 값에 따라 재시도가 되는지?
 

테스트 1. IOException 발생 시 재시도

WireMock의 Fault.CONNECTION_RESET_BY_PEER를 사용하면 IOException을 발생시킬 수 있습니다.

@Test
@DisplayName("IOException 발생 시 설정된 횟수만큼 재시도한다")
void retryOnIOException() {
    // Given: WireMock이 CONNECTION_RESET_BY_PEER 오류를 반환하도록 설정
    stubFor(get(GithubClient.DOCKER_REPO_URL)
            .willReturn(aResponse()
                    .withFault(Fault.CONNECTION_RESET_BY_PEER)));

    // When: FeignClient 호출
    assertThatThrownBy(() -> githubClient.getAllDockerImages())
            .isInstanceOf(RetryableException.class)
            .hasCauseInstanceOf(IOException.class);

    // Then: 설정된 횟수만큼 재시도 확인
    /**
     * 주의: WireMock이 내부적으로 사용하는 ApacheHttpClient가 
     * IOException 발생 시 자동으로 1회 재시도하기 때문에 실제 요청 횟수는 *2가 됩니다.
     * 
     * 참고: https://github.com/wiremock/wiremock/issues/1789
     */
    verify(FEIGN_RETRY_MAX_ATTEMPTS * 2, 
           getRequestedFor(urlEqualTo(GithubClient.DOCKER_REPO_URL)));
}

 
주의사항: WireMock의 ApacheClient 재시도

디버거로 retryer.continueOrPropagate(e) 메서드에 브레이킹 포인트를 찍어보면 정확히 5번 호출되는 것을 확인할 수 있습니다.
그런데 WireMock의 요청 카운트는 10번(5 × 2)으로 나옵니다.
이유는 WireMock이 내부적으로 사용하는 ApacheHttpClient가 IOException 발생 시 자동으로 1회 재시도하기 때문입니다.
 
참고 자료

• WireMock Issue #1789
• Apache HttpClient - DefaultHttpRequestRetryStrategy

 
이렇게 외부 라이브러리의 동작에 의존하는 테스트는 나중에 깨질 우려가 있습니다.
따라서 이 테스트는 코드로 작성하기보다는 디버거로 retryer.continueOrPropagate(e)가 올바르게 호출되는지 확인하는 정도면 충분하다는 생각이 듭니다.
 

테스트 2. Retry-After 헤더 있을 때 재시도

이번에는 실질적으로 유용한 테스트입니다.
WireMock 응답에 Retry-After 헤더를 추가하여 재시도 횟수를 검증합니다.

@ParameterizedTest
@DisplayName("Retry-After 헤더가 있으면 설정된 횟수만큼 재시도한다")
@ValueSource(ints = {403, 429})
void retryWithRetryAfterHeader(int responseCode) {
    // Given: HTTP 에러 응답 + Retry-After 헤더
    stubFor(get(GithubClient.DOCKER_REPO_URL)
            .willReturn(aResponse()
                    .withStatus(responseCode)
                    .withHeader(HttpHeaders.RETRY_AFTER, "1")));

    // When: FeignClient 호출
    assertThatThrownBy(() -> githubClient.getAllDockerImages())
            .isInstanceOf(RetryableException.class);

    // Then: 재시도 횟수 검증
    verify(FEIGN_RETRY_MAX_ATTEMPTS, 
           getRequestedFor(urlEqualTo(GithubClient.DOCKER_REPO_URL)));
}

 

테스트 3. Retry-After 우선순위 검증

마지막으로 Retry-After 헤더와 Retryer.Default 설정 시간 중, 더 작은 값이 재시도 간격의 상한선을 결정하는지 검증할 수도 있습니다.

    @Test
    @DisplayName("Retry-After 헤더와 Retryer.Default 설정 시간 중, 더 작은 값이 재시도 간격의 상한선을 결정한다")
    void retryTime() {
        Duration strictRetryAfterSeconds = Duration.ofSeconds(3);
        stubFor(get(GithubClient.DOCKER_REPO_URL)
                .willReturn(aResponse()
                        .withStatus(429)
                        .withHeader(HttpHeaders.RETRY_AFTER, String.valueOf(strictRetryAfterSeconds.getSeconds()))));

        long start = System.currentTimeMillis();
        assertThatThrownBy(() -> githubClient.getAllDockerImages())
                .isInstanceOf(RetryableException.class);

        Duration actualTime = Duration.ofMillis(System.currentTimeMillis() - start);
        Duration expectedTime = strictRetryAfterSeconds.multipliedBy(FEIGN_RETRY_MAX_ATTEMPTS - 1);
        assertThat(actualTime).isGreaterThanOrEqualTo(expectedTime);
    }

 
만약, 서버가 응답한 Retry-After 헤더의 값을 엄격하게 지키고 싶다면, Retryer 의 continueOrPropagate( ) 를 오버라이딩해야 합니다.
 
다음은 전체 테스트 코드입니다.
- FeignClient 설정

@Configuration
@EnableFeignClients
public class GlobalFeignClientConfig {
    public static final int FEIGN_RETRY_MAX_ATTEMPTS = 3;

    /**
     * 1. Retry-After 헤더 존재 시, 해당 헤더 시간을 엄격하게 존중
     * 2. Retry-After 헤더 없을 시, 0.1초의 간격으로 시작해 최대 3초의 간격으로 점점 증가하며, 최대 3번 시도한다.
     */
    @Bean
    Retryer.Default retryer() {
        return new Retryer.Default(100L, TimeUnit.SECONDS.toMillis(3L), FEIGN_RETRY_MAX_ATTEMPTS);
    }
}

 
- FeignClient 설정 코드

import com.github.tomakehurst.wiremock.client.WireMock;
import com.github.tomakehurst.wiremock.http.Fault;
import feign.RetryableException;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.cloud.contract.wiremock.AutoConfigureWireMock;
import org.springframework.http.HttpHeaders;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.context.TestPropertySource;

import java.io.IOException;
import java.time.Duration;

import static com.github.tomakehurst.wiremock.client.WireMock.*;
import static jonghyeok.onpremiseinstallsupporter.GlobalFeignClientConfig.FEIGN_RETRY_MAX_ATTEMPTS;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.assertj.core.api.AssertionsForClassTypes.assertThat;

@SpringBootTest
@ActiveProfiles(value = "test")
@AutoConfigureWireMock(port = GithubClientMockTest.RANDOM_PORT)
@TestPropertySource(properties = "github.url=http://localhost:${wiremock.server.port}")
public class GithubClientMockTest {
    static final int RANDOM_PORT = 0;

    @Autowired
    GithubClient githubClient;

    @BeforeEach
    void setUp() {
        WireMock.resetAllRequests();
    }

    @ParameterizedTest
    @DisplayName("응답에 Retry-After 헤더가 있으면 재시도 설정 횟수만큼 재시도 한다.")
    @ValueSource(ints = {403, 429})
    void retryFivesTimesByResponseCode(int responseCode) {
        stubFor(get(GithubClient.DOCKER_REPO_URL)
                .willReturn(aResponse()
                        .withStatus(responseCode)
                        .withHeader(HttpHeaders.RETRY_AFTER, "1")));

        assertThatThrownBy(() -> githubClient.getAllDockerImages())
                .isInstanceOf(RetryableException.class);

        verify(FEIGN_RETRY_MAX_ATTEMPTS, getRequestedFor(urlEqualTo(GithubClient.DOCKER_REPO_URL)));
    }

    @Test
    @DisplayName("Retry-After 헤더와 Retryer.Default 설정 시간 중, 더 작은 값이 재시도 간격의 상한선을 결정한다")
    void strictRetry() {
        Duration strictRetryAfterSeconds = Duration.ofSeconds(3);
        stubFor(get(GithubClient.DOCKER_REPO_URL)
                .willReturn(aResponse()
                        .withStatus(429)
                        .withHeader(HttpHeaders.RETRY_AFTER, String.valueOf(strictRetryAfterSeconds.getSeconds()))));

        long start = System.currentTimeMillis();
        assertThatThrownBy(() -> githubClient.getAllDockerImages())
                .isInstanceOf(RetryableException.class);

        Duration actualTime = Duration.ofMillis(System.currentTimeMillis() - start);
        Duration expectedTime = strictRetryAfterSeconds.multipliedBy(FEIGN_RETRY_MAX_ATTEMPTS - 1);
        assertThat(actualTime).isLessThanOrEqualTo(expectedTime);
    }

    @Test
    @DisplayName("IOException 발생 시 설정된 횟수만큼 재시도한다.")
    void retryOnIOException() {
        stubFor(get(GithubClient.DOCKER_REPO_URL)
                .willReturn(aResponse()
                        .withFault(Fault.CONNECTION_RESET_BY_PEER)));

        assertThatThrownBy(() -> githubClient.getAllDockerImages())
                .isInstanceOf(RetryableException.class)
                .hasCauseInstanceOf(IOException.class);

        /**
         * https://github.com/wiremock/wiremock/issues/1789
         * WireMock 에서 사용중인 ApacheHttpClient 가 IOException 발생 시, 기본적으로 1회 재시도 시도하기 때문에 *2 를 함.
         */
        verify(FEIGN_RETRY_MAX_ATTEMPTS * 2, getRequestedFor(urlEqualTo(GithubClient.DOCKER_REPO_URL)));
    }
}