---
title: Spring Framework — RestClient (Synchronous Fluent HTTP Client, Builder, ClientHttpRequestFactory)
source_type: official-doc
url: https://docs.spring.io/spring-framework/reference/integration/rest-clients.html
archive_url:
related_projects: []
related_branches: [feature-outbound-http-client-baseline]
tags: [spring-framework, rest-client, http-client, builder-pattern, jdk-http-client, apache-http-client, jetty, reactor-netty, interceptor, official-doc]
status: raw
confidence: high
created: 2026-05-27
last_reviewed: 2026-05-27
---

# Spring Framework — RestClient (Synchronous Fluent HTTP Client, Builder, ClientHttpRequestFactory)

> Layer: `raw/official-docs/` — Spring Framework Reference / "REST Clients" 페이지 verbatim (RestClient 중심).
> outbound HTTP client baseline 의 동기 호출 mechanism (RestClient + ClientHttpRequestFactory + interceptor) 의 1차 근거.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-outbound-http-client-baseline]] | D5 mechanism — RestClient.builder() 로 baseUrl/defaultHeader/interceptor 를 설정하고 ClientHttpRequestFactory 로 underlying HTTP library 를 선택하는 baseline. D7 mechanism — onStatus 를 통한 error handling override (default 는 4xx/5xx 에서 RestClientException 의 subclass throw) |

## 컨텍스트

ca-tmpl 의 outbound HTTP client baseline 은 RestTemplate 가 아닌 RestClient 를 사용한다. 이유: Spring Framework 7.0 에서 RestTemplate 가 deprecated 되었고, RestClient 가 동일 동기 API + fluent + thread-safe + 다양한 HTTP library 선택 가능. 본 자료는 (1) RestClient builder option, (2) ClientHttpRequestFactory 의 5가지 구현체, (3) 기본 4xx/5xx error 처리, (4) thread safety 의 4가지 사실을 verbatim 으로 보존.

## 출처 / Source

- 원본 URL: https://docs.spring.io/spring-framework/reference/integration/rest-clients.html
- 아카이브 URL: (미수집)
- 저자 / 조직: Spring Framework (VMware / Broadcom)
- 발행일: rolling docs (current = 7.x)
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

> [§REST Clients Overview] "The Spring Framework provides the following choices for making calls to REST endpoints: `RestClient` — synchronous client with a fluent API"

> [§RestClient Introduction] "`RestClient` is a synchronous HTTP client that provides a fluent API to perform requests. It serves as an abstraction over HTTP libraries, and handles conversion of HTTP request and response content to and from higher level Java objects."

> [§Create a RestClient - Builder Pattern] "`RestClient` has static `create` shortcut methods. It also exposes a `builder()` with further options: select the HTTP library to use, see Client Request Factories; configure message converters, see HTTP Message Conversion; set a baseUrl; set default request headers, cookies, path variables, API version; configure an `ApiVersionInserter`; register interceptors; register request initializers"

> [§RestTemplate Deprecation] "As of Spring Framework 7.0, `RestTemplate` is deprecated in favor of `RestClient` and will be removed in a future version, please use the 'Migrating to RestClient' guide."

> [§Client Request Factories] "To execute the HTTP request, `RestClient` uses a client HTTP library. These libraries are adapted via the `ClientRequestFactory` interface. Various implementations are available: `JdkClientHttpRequestFactory` for Java's `HttpClient`; `HttpComponentsClientHttpRequestFactory` for use with Apache HTTP Components `HttpClient`; `JettyClientHttpRequestFactory` for Jetty's `HttpClient`; `ReactorNettyClientRequestFactory` for Reactor Netty's `HttpClient`; `SimpleClientHttpRequestFactory` as a simple default"

> [§Error Handling via onStatus] "By default, `RestClient` throws a subclass of `RestClientException` when retrieving a response with a 4xx or 5xx status code. This behavior can be overridden using `onStatus`."

> [§Fluent API - Request Setup] "To perform an HTTP request, first specify the HTTP method to use. Use the convenience methods like `get()`, `head()`, `post()`, and others, or `method(HttpMethod)`. Next, specify the request URI with the `uri` methods."

> [§Thread Safety] "Once created, a `RestClient` is safe to use in multiple threads."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| SPRING-RESTCLIENT-REF-C1 | RestClient 는 fluent API 를 제공하는 synchronous HTTP client 이고, HTTP library 추상화 + request/response 와 Java 객체 간 변환을 처리한다 | [§RestClient Introduction] "`RestClient` is a synchronous HTTP client that provides a fluent API to perform requests. It serves as an abstraction over HTTP libraries, and handles conversion of HTTP request and response content to and from higher level Java objects." | `official-vendor-doc` | Spring Framework 6.1+ / 7.x | reactive (WebClient) 와의 성능 비교/선택 가이드는 본 인용 범위 밖 |
| SPRING-RESTCLIENT-REF-C2 | RestClient 는 `create()` 단축 메서드 외에 `builder()` 를 제공하며, builder 옵션은: HTTP library 선택, message converter, baseUrl, default request header/cookie/path variable/API version, ApiVersionInserter, interceptor, request initializer 등록 | [§Create a RestClient - Builder Pattern] "`RestClient` has static `create` shortcut methods. It also exposes a `builder()` with further options: select the HTTP library to use, see Client Request Factories; configure message converters, see HTTP Message Conversion; set a baseUrl; set default request headers, cookies, path variables, API version; configure an `ApiVersionInserter`; register interceptors; register request initializers" | `official-vendor-doc` | RestClient.builder() 사용 시 | timeout 설정이 builder 에서 직접 지원되는지 (vs RequestFactory 에서 설정) 는 별도 페이지 참조 |
| SPRING-RESTCLIENT-REF-C3 | Spring Framework 7.0 부터 RestTemplate 가 deprecated 되고 RestClient 로 대체될 예정. 향후 버전에서 제거 | [§RestTemplate Deprecation] "As of Spring Framework 7.0, `RestTemplate` is deprecated in favor of `RestClient` and will be removed in a future version, please use the 'Migrating to RestClient' guide." | `official-vendor-doc` | Spring Framework 7.0+ | 제거 시점의 정확한 버전은 명시되지 않음 ("future version") |
| SPRING-RESTCLIENT-REF-C4 | RestClient 는 underlying HTTP library 를 `ClientRequestFactory` interface 로 추상화. 가용 구현체 5개: JDK HttpClient, Apache HttpComponents, Jetty, Reactor Netty, SimpleClientHttpRequestFactory (default) | [§Client Request Factories] "These libraries are adapted via the `ClientRequestFactory` interface. Various implementations are available: `JdkClientHttpRequestFactory` for Java's `HttpClient`; `HttpComponentsClientHttpRequestFactory`...; `JettyClientHttpRequestFactory`...; `ReactorNettyClientRequestFactory`...; `SimpleClientHttpRequestFactory` as a simple default" | `official-vendor-doc` | RestClient 의 모든 baseline 선택 | 각 RequestFactory 의 connect/read timeout default 값은 본 인용 범위 밖 — 각 구현체 docs 별도 |
| SPRING-RESTCLIENT-REF-C5 | RestClient 는 default 로 4xx/5xx response 에서 `RestClientException` 의 subclass 를 throw 하며, 이 동작은 `onStatus` 로 override 가능 | [§Error Handling via onStatus] "By default, `RestClient` throws a subclass of `RestClientException` when retrieving a response with a 4xx or 5xx status code. This behavior can be overridden using `onStatus`." | `official-vendor-doc` | RestClient `.retrieve()` chain 사용 시 | `.exchange()` 사용 시 동일한지 (exchange 는 status handler 우회 가능) 는 본 인용 범위 밖 |
| SPRING-RESTCLIENT-REF-C6 | 요청은 HTTP method 지정 (`get()`/`head()`/`post()`/`method(HttpMethod)`) 후 `uri` 메서드로 URI 지정하는 fluent 형태 | [§Fluent API - Request Setup] "To perform an HTTP request, first specify the HTTP method to use. Use the convenience methods like `get()`, `head()`, `post()`, and others, or `method(HttpMethod)`. Next, specify the request URI with the `uri` methods." | `official-vendor-doc` | RestClient API 호출 시 | request body 지정 / message converter 선택 메커니즘은 별도 인용 필요 |
| SPRING-RESTCLIENT-REF-C7 | 한번 생성된 RestClient instance 는 multiple thread 에서 안전하게 사용 가능 | [§Thread Safety] "Once created, a `RestClient` is safe to use in multiple threads." | `official-vendor-doc` | RestClient instance (생성 완료 후) | builder 자체가 thread-safe 한지는 본 인용 범위 밖 (builder 는 immutable build 후 사용 권장) |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `SPRING-RESTCLIENT-REF-C1`: RestClient = synchronous + fluent + HTTP library 추상화
  - `SPRING-RESTCLIENT-REF-C2`: builder() 의 정확한 옵션 목록
  - `SPRING-RESTCLIENT-REF-C3`: Spring Framework 7.0 부터 RestTemplate deprecation
  - `SPRING-RESTCLIENT-REF-C4`: ClientRequestFactory 의 5개 구현체 명칭
  - `SPRING-RESTCLIENT-REF-C5`: default 4xx/5xx error 처리 + onStatus override
  - `SPRING-RESTCLIENT-REF-C6`: HTTP method → uri 의 fluent 순서
  - `SPRING-RESTCLIENT-REF-C7`: 생성 후 multi-thread 안전
- **이 자료가 증명하지 않는 것**:
  - RestClient 가 WebClient 보다 throughput 이 좋다 — synchronous 와 reactive 의 성능 트레이드오프는 본 인용 범위 밖
  - 각 ClientHttpRequestFactory 의 default connect/read timeout 값
  - Resilience4j CircuitBreaker / Retry 와의 통합 패턴 (별도 Resilience4j docs 필요)
  - retry / circuit-breaking 이 RestClient builder 의 빌트인 기능이라는 뜻은 **아님** — 별도 library 필요
  - HTTP/2 / HTTP/3 지원 여부는 underlying RequestFactory 별로 다름
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 의 RestClient bean 이 어떤 `ClientHttpRequestFactory` 를 사용하는지 (Spring Boot 의 RestClient.Builder bean 의 default)
  - `JdkClientHttpRequestFactory` 의 connect timeout 설정 위치 (factory side vs builder side)
  - interceptor (`ClientHttpRequestInterceptor`) 가 retry 횟수만큼 호출되는지 (Resilience4j Retry 와의 layering 순서)

## 메모 / Notes

- 인용 1 해석 후보 (미검증):
  - Spring Boot 3.4+ 는 RestClient.Builder bean 을 auto-config 한다고 알려져 있으나 본 인용 범위 밖 — Spring Boot 별 페이지 참조 필요
- 추가로 봐야 할 동일 출처 페이지:
  - `https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-restclient-builder` (builder 상세)
  - `https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-request-factories` (각 factory 별 timeout)

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/resilience4j-micrometer-module]] (CB/Retry metric)
  - [[raw/official-docs/spring-smartlifecycle-reference]] (client 의 graceful start/stop)
- 인용하는 branch:
  - [[raw/branch-notes/feature-outbound-http-client-baseline]]
- 인용하는 project:
  - [[raw/project-notes/ca-skeleton-operational-contract]]
- 인용하는 wiki: (미작성)