RestClient로 외부 API 호출하기

RestClient로 외부 API 호출하기 Spring Boot 4의 RestClient로 외부 API를 호출하는 법. 타임아웃·에러 핸들링·재시도를 코드로 구현하고 RestTemplate과 비교한다.

---

들어가며

이전 글에서 외부 API 연동 시 타임아웃을 반드시 설정해야 한다는 이야기를 했다.
그 글은 "왜"에 집중했고 실제 코드는 많지 않았다.
이번 글은 그 연장선으로, 어떻게 구현하는지를 코드 중심으로 정리한다.

Spring Boot 3.2 / Spring Framework 6.1부터 RestClient가 도입됐다.
RestTemplate을 대체하기 위한 동기(Synchronous) HTTP 클라이언트로, 메서드 체이닝 기반의 fluent API를 제공한다.
Spring Boot 4.0에서는 프로퍼티 네이밍까지 정리되면서 사실상 RestTemplate 대신 RestClient를 쓰지 않을 이유가 없어졌다.

이 글에서는 RestClient 빈 등록 → 타임아웃 → 에러 핸들링 → 로깅 인터셉터 → 재시도까지 전체를 구현한다.

---

RestTemplate vs RestClient

먼저 마이그레이션 관점에서 두 클라이언트를 비교한다.

항목	RestTemplate	RestClient
도입 시점	Spring 3.0	Spring 6.1 / Boot 3.2
API 스타일	메서드 기반 (getForObject, postForEntity)	fluent 체이닝 (.get().uri().retrieve())
에러 핸들링	ResponseErrorHandler 구현체 등록	.onStatus() 인라인 핸들러
타임아웃 설정	RequestFactory 직접 생성 후 주입	ClientHttpRequestFactorySettings (간결)
인터셉터	ClientHttpRequestInterceptor	ClientHttpRequestInterceptor (동일)
Spring 6.1+	유지보수 모드 (신규 기능 없음)	공식 권장

RestTemplate이 deprecated된 건 아니지만, 공식적으로 신규 기능 추가는 없다.
새 프로젝트라면 처음부터 RestClient로 시작하는 게 맞다.

---

의존성

RestClient는 spring-boot-starter-web에 포함되어 있어 별도 의존성이 필요 없다.
재시도(@Retryable)를 위해 spring-retry만 추가한다.

// build.gradle.kts
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.retry:spring-retry")
    implementation("org.springframework:spring-aspects")   // @Retryable AOP 필수
}

---

전체 구조

구현할 레이어는 다음과 같다.

┌─────────────────────────────────────────────────────────────┐
│                        Service Layer                        │
│            UserApiClient / PaymentApiClient ...             │
└────────────────────────┬────────────────────────────────────┘
                         │ RestClient 호출
┌────────────────────────▼────────────────────────────────────┐
│                     RestClient Bean                         │
│                                                             │
│  ┌─────────────────┐    ┌──────────────────────────────┐   │
│  │ LoggingIntercep │    │  ClientHttpRequestFactory    │   │
│  │     -tor        │    │  (Connect / Read Timeout)    │   │
│  └────────┬────────┘    └──────────────┬───────────────┘   │
│           │                            │                    │
│           └───────────┬────────────────┘                    │
└───────────────────────┼─────────────────────────────────────┘
                        │ HTTP 요청
              ┌─────────▼──────────┐
              │   External API     │
              └─────────┬──────────┘
                        │ 응답
          ┌─────────────▼──────────────┐
          │      onStatus Handler      │
          │  4xx → ClientException     │
          │  5xx → ServerException     │
          │          ↓ 5xx             │
          │    @Retryable (retry)      │
          └────────────────────────────┘

---

RestClientConfig — 빈 등록과 타임아웃

application.yml (Spring Boot 4.0 방식)

Spring Boot 4.0에서 HTTP 클라이언트 프로퍼티 네임스페이스가 정리됐다.
spring.http.client.*는 deprecated되고 spring.http.clients.*로 통합됐다.

# application.yml
spring:
  http:
    clients:
      connect-timeout: 3s     # 연결 타임아웃
      read-timeout: 10s       # 읽기 타임아웃

프로퍼티로 전역 설정하고 싶을 때 쓴다.
다만 외부 API별로 타임아웃을 달리 가져가야 한다면 아래 코드 방식을 쓴다.

RestClientConfig.java

// src/main/java/com/example/config/RestClientConfig.java
package com.example.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.ClientHttpRequestFactory;
import org.springframework.http.client.ClientHttpRequestFactories;
import org.springframework.http.client.ClientHttpRequestFactorySettings;
import org.springframework.web.client.RestClient;

import java.time.Duration;

@Configuration
public class RestClientConfig {

    /**
     * 결제 API 전용 클라이언트 — 타임아웃을 짧게 가져간다.
     * 결제 연동은 응답이 늦어지는 순간 스레드가 묶이기 때문이다.
     */
    @Bean("paymentRestClient")
    public RestClient paymentRestClient(
            LoggingInterceptor loggingInterceptor,
            @Value("${external.payment.base-url}") String baseUrl
    ) {
        return RestClient.builder()
                .baseUrl(baseUrl)
                .requestFactory(buildRequestFactory(Duration.ofSeconds(3), Duration.ofSeconds(5)))
                .requestInterceptor(loggingInterceptor)
                .build();
    }

    /**
     * 사용자 API 전용 클라이언트 — 응답이 느릴 수 있어 읽기 타임아웃을 넉넉하게 잡는다.
     */
    @Bean("userRestClient")
    public RestClient userRestClient(
            LoggingInterceptor loggingInterceptor,
            @Value("${external.user.base-url}") String baseUrl
    ) {
        return RestClient.builder()
                .baseUrl(baseUrl)
                .requestFactory(buildRequestFactory(Duration.ofSeconds(3), Duration.ofSeconds(15)))
                .requestInterceptor(loggingInterceptor)
                .build();
    }

    private ClientHttpRequestFactory buildRequestFactory(
            Duration connectTimeout,
            Duration readTimeout
    ) {
        ClientHttpRequestFactorySettings settings = ClientHttpRequestFactorySettings.defaults()
                .withConnectTimeout(connectTimeout)
                .withReadTimeout(readTimeout);

        // Spring Boot 4 기본 팩토리는 JDK HttpClient
        // Apache HttpComponents로 바꾸려면 ClientHttpRequestFactories.get(HttpComponentsClientHttpRequestFactory.class, settings)
        return ClientHttpRequestFactories.get(settings);
    }
}

# application.yml
external:
  payment:
    base-url: ${PAYMENT_API_URL}
  user:
    base-url: ${USER_API_URL}

---

커스텀 예외 클래스

에러 핸들링에서 던질 예외를 먼저 정의한다.
4xx(클라이언트 에러)와 5xx(서버 에러)를 구분하는 게 핵심이다.

// src/main/java/com/example/exception/ExternalApiException.java
package com.example.exception;

import org.springframework.http.HttpStatusCode;

public class ExternalApiException extends RuntimeException {

    private final HttpStatusCode statusCode;

    public ExternalApiException(HttpStatusCode statusCode, String message) {
        super(message);
        this.statusCode = statusCode;
    }

    public HttpStatusCode getStatusCode() {
        return statusCode;
    }
}

// src/main/java/com/example/exception/ExternalApiClientException.java
package com.example.exception;

import org.springframework.http.HttpStatusCode;

/**
 * 4xx — 잘못된 요청, 인증 실패 등. 재시도해도 동일한 결과가 나온다.
 */
public class ExternalApiClientException extends ExternalApiException {

    public ExternalApiClientException(HttpStatusCode statusCode, String message) {
        super(statusCode, message);
    }
}

// src/main/java/com/example/exception/ExternalApiServerException.java
package com.example.exception;

import org.springframework.http.HttpStatusCode;

/**
 * 5xx — 일시적인 서버 오류. 재시도 대상이다.
 */
public class ExternalApiServerException extends ExternalApiException {

    public ExternalApiServerException(HttpStatusCode statusCode, String message) {
        super(statusCode, message);
    }
}

---

로깅 인터셉터

요청/응답을 로그로 남기는 인터셉터다.
운영 환경에서 외부 API 연동 문제를 추적할 때 없으면 답답한 기능이다.

// src/main/java/com/example/config/LoggingInterceptor.java
package com.example.config;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpRequest;
import org.springframework.http.client.ClientHttpRequestExecution;
import org.springframework.http.client.ClientHttpRequestInterceptor;
import org.springframework.http.client.ClientHttpResponse;
import org.springframework.stereotype.Component;

import java.io.IOException;
import java.nio.charset.StandardCharsets;

@Component
public class LoggingInterceptor implements ClientHttpRequestInterceptor {

    private static final Logger log = LoggerFactory.getLogger(LoggingInterceptor.class);

    @Override
    public ClientHttpResponse intercept(
            HttpRequest request,
            byte[] body,
            ClientHttpRequestExecution execution
    ) throws IOException {
        logRequest(request, body);
        long start = System.currentTimeMillis();

        ClientHttpResponse response = execution.execute(request, body);

        logResponse(request, response, System.currentTimeMillis() - start);
        return response;
    }

    private void logRequest(HttpRequest request, byte[] body) {
        log.info("[RestClient] → {} {} | body: {}",
                request.getMethod(),
                request.getURI(),
                body.length > 0 ? new String(body, StandardCharsets.UTF_8) : "(empty)"
        );
    }

    private void logResponse(HttpRequest request, ClientHttpResponse response, long elapsedMs) throws IOException {
        log.info("[RestClient] ← {} {} | status: {} | elapsed: {}ms",
                request.getMethod(),
                request.getURI(),
                response.getStatusCode(),
                elapsedMs
        );
    }
}

---

에러 핸들링 — onStatus

RestClient는 .retrieve().onStatus()로 상태 코드별 핸들러를 인라인으로 등록한다.
RestTemplate에서 ResponseErrorHandler를 별도 구현체로 등록하던 방식보다 훨씬 간결하다.

방식	RestTemplate	RestClient
에러 핸들러 등록	setErrorHandler(ResponseErrorHandler)	.onStatus(predicate, handler) 체이닝
상태 코드 조건	hasError(HttpStatusCode) 오버라이드	HttpStatusCode::is4xxClientError 람다
응답 바디 접근	handleError(ClientHttpResponse)에서 처리	handler 두 번째 파라미터 ClientHttpResponse로 접근

실제로 어떻게 쓰는지 아래 UserApiClient에서 보자.

---

UserApiClient 구현

// src/main/java/com/example/client/UserApiClient.java
package com.example.client;

import com.example.exception.ExternalApiClientException;
import com.example.exception.ExternalApiServerException;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.http.MediaType;
import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.Recover;
import org.springframework.retry.annotation.Retryable;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestClient;

import java.nio.charset.StandardCharsets;

@Component
public class UserApiClient {

    private final RestClient restClient;

    public UserApiClient(@Qualifier("userRestClient") RestClient restClient) {
        this.restClient = restClient;
    }

    /**
     * 사용자 단건 조회.
     * 5xx 에러 시 최대 3회(초기 포함) 재시도, 지수 백오프 적용.
     */
    @Retryable(
            retryFor = ExternalApiServerException.class,
            maxAttempts = 3,
            backoff = @Backoff(delay = 500, multiplier = 2.0, maxDelay = 5000)
    )
    public UserResponse getUser(Long userId) {
        return restClient.get()
                .uri("/users/{id}", userId)
                .retrieve()
                .onStatus(status -> status.value() == 404, (req, res) -> {
                    throw new ExternalApiClientException(res.getStatusCode(),
                            "User not found: " + userId);
                })
                .onStatus(status -> status.is4xxClientError(), (req, res) -> {
                    String body = new String(res.getBody().readAllBytes(), StandardCharsets.UTF_8);
                    throw new ExternalApiClientException(res.getStatusCode(), body);
                })
                .onStatus(status -> status.is5xxServerError(), (req, res) -> {
                    String body = new String(res.getBody().readAllBytes(), StandardCharsets.UTF_8);
                    // ExternalApiServerException → @Retryable이 감지해 재시도
                    throw new ExternalApiServerException(res.getStatusCode(), body);
                })
                .body(UserResponse.class);
    }

    /**
     * 사용자 생성.
     * POST는 멱등하지 않으므로 재시도 없이 그대로 실패를 전파한다.
     */
    public UserResponse createUser(CreateUserRequest request) {
        return restClient.post()
                .uri("/users")
                .contentType(MediaType.APPLICATION_JSON)
                .body(request)
                .retrieve()
                .onStatus(status -> status.is4xxClientError(), (req, res) -> {
                    String body = new String(res.getBody().readAllBytes(), StandardCharsets.UTF_8);
                    throw new ExternalApiClientException(res.getStatusCode(), body);
                })
                .onStatus(status -> status.is5xxServerError(), (req, res) -> {
                    String body = new String(res.getBody().readAllBytes(), StandardCharsets.UTF_8);
                    throw new ExternalApiServerException(res.getStatusCode(), body);
                })
                .body(UserResponse.class);
    }

    /**
     * 사용자 삭제.
     * 응답 바디가 없을 때는 .toBodilessEntity()를 사용한다.
     */
    public void deleteUser(Long userId) {
        restClient.delete()
                .uri("/users/{id}", userId)
                .retrieve()
                .onStatus(status -> status.is4xxClientError(), (req, res) -> {
                    throw new ExternalApiClientException(res.getStatusCode(),
                            "Delete failed for userId: " + userId);
                })
                .onStatus(status -> status.is5xxServerError(), (req, res) -> {
                    throw new ExternalApiServerException(res.getStatusCode(),
                            "Server error while deleting userId: " + userId);
                })
                .toBodilessEntity();
    }

    /**
     * getUser 재시도 소진 후 최종 실패 처리.
     * @Recover 메서드 시그니처: 첫 번째 파라미터가 재시도 예외, 나머지는 원본 파라미터와 동일해야 한다.
     */
    @Recover
    public UserResponse recoverGetUser(ExternalApiServerException e, Long userId) {
        throw new IllegalStateException(
                "External user API unavailable after retries. userId=" + userId, e
        );
    }
}

---

DTO 정의

// src/main/java/com/example/client/UserResponse.java
package com.example.client;

public record UserResponse(
        Long id,
        String email,
        String name,
        String role
) {}

// src/main/java/com/example/client/CreateUserRequest.java
package com.example.client;

public record CreateUserRequest(
        String email,
        String name
) {}

---

@EnableRetry 등록

@Retryable은 AOP 기반이라 메인 클래스나 설정 클래스에 @EnableRetry를 선언해야 한다.

// src/main/java/com/example/Application.java
package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.retry.annotation.EnableRetry;

@SpringBootApplication
@EnableRetry
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

---

전체 요청 흐름

구현한 흐름을 정리하면 다음과 같다.

서비스 레이어
   │
   │── UserApiClient.getUser(userId) 호출
   │
   ▼
RestClient (userRestClient 빈)
   │
   ├── LoggingInterceptor
   │     └── 요청/응답 로그 기록 + 소요 시간 측정
   │
   ├── ClientHttpRequestFactory
   │     ├── Connect Timeout: 3s
   │     └── Read Timeout: 15s
   │
   │── GET /users/{id} ──────────────────────────────► External User API
   │                                                          │
   │◄─────────────────────────────────────────────── HTTP 응답
   │
   ├── [200 OK]
   │     └── .body(UserResponse.class) → 역직렬화 → 반환
   │
   ├── [404 Not Found]
   │     └── onStatus → ExternalApiClientException (재시도 없음)
   │
   ├── [4xx]
   │     └── onStatus → ExternalApiClientException (재시도 없음)
   │
   ├── [5xx]
   │     └── onStatus → ExternalApiServerException
   │               │
   │               └── @Retryable 감지
   │                     ├── 1차 재시도 (500ms 후)
   │                     ├── 2차 재시도 (1000ms 후)
   │                     └── 소진 → @Recover → IllegalStateException
   │
   └── [Timeout]
         └── ResourceAccessException → 호출부로 전파

---

RestTemplate → RestClient 마이그레이션 요약

기존 코드를 교체할 때 자주 쓰이는 패턴만 표로 정리한다.

RestTemplate (구)	RestClient (신)
restTemplate.getForObject(url, ResponseType.class)	.get().uri(url).retrieve().body(ResponseType.class)
restTemplate.getForEntity(url, ResponseType.class)	.get().uri(url).retrieve().toEntity(ResponseType.class)
restTemplate.postForObject(url, req, ResponseType.class)	.post().uri(url).body(req).retrieve().body(ResponseType.class)
restTemplate.exchange(url, method, entity, type)	.method(method).uri(url).body(...).retrieve()...
restTemplate.delete(url)	.delete().uri(url).retrieve().toBodilessEntity()
setErrorHandler(new MyErrorHandler())	.onStatus(predicate, handler) 체이닝
setInterceptors(List.of(interceptor))	.requestInterceptor(interceptor) 체이닝

URI 변수 치환은 두 클라이언트 모두 동일하게 지원한다.

// RestTemplate
restTemplate.getForObject("/users/{id}", UserResponse.class, userId);

// RestClient — 방법 1: 가변 인수
restClient.get().uri("/users/{id}", userId)...

// RestClient — 방법 2: 람다 (쿼리 파라미터가 많을 때)
restClient.get()
    .uri(uriBuilder -> uriBuilder
            .path("/users")
            .queryParam("email", email)
            .queryParam("page", page)
            .build())
    ...

---

마치며

RestClient로 넘어오면서 에러 핸들링과 타임아웃 설정이 눈에 띄게 간결해졌다.
ResponseErrorHandler 구현체를 별도 클래스로 만들고, RestTemplate 빈에 .setErrorHandler()로 주입하던 흐름이 .onStatus() 한 줄로 압축된다.

중요한 포인트를 다시 짚으면:

• ClientHttpRequestFactorySettings.defaults()로 타임아웃을 선언하고, 외부 API별 빈을 분리해서 타임아웃을 다르게 관리한다.
• 4xx는 재시도하지 않는다. 잘못된 요청을 100번 다시 보내도 결과는 같다.
• POST처럼 멱등하지 않은 요청에는 @Retryable을 붙이지 않는다. 같은 주문이 두 번 생성될 수 있다.
• @Recover 메서드의 파라미터 순서를 반드시 지킨다. 첫 번째가 예외, 나머지는 원본 메서드의 파라미터와 동일해야 Spring Retry가 매핑한다.
• Spring Boot 4.0에서 spring.http.client.* 프로퍼티는 deprecated됐다. spring.http.clients.*로 쓴다.

타임아웃이 왜 필요한지는 이전 글에서 다뤘다.
이제 코드로 짜는 방법도 갖춰졌으니, 다음 연동 작업에서는 바로 꺼내 쓰면 된다.

---

참고 출처

• Spring Framework 6.1 RestClient Docs — https://docs.spring.io/spring-framework/reference/integration/rest-clients.html
• Spring Boot 4.0 Configuration Changelog — https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Configuration-Changelog
• Spring Retry Docs — https://docs.spring.io/spring-retry/docs/current/reference/html/
• RFC 7231: HTTP/1.1 Semantics — https://datatracker.ietf.org/doc/html/rfc7231