llm-wiki/raw/official-docs/outbound-spring-restclient-baseline.md

---
title: Spring RestClient — synchronous HTTP client baseline (Spring 6.1+)
source_type: official-doc
status: raw
confidence: high
url: https://docs.spring.io/spring-framework/reference/integration/rest-clients.html
archive_url:
related_branches: [feature-outbound-http-client-baseline, feature-integration-adapter-templates]
related_projects: [ca-tmpl]
tags: [ca-outbound-http, spring, restclient, resttemplate, webclient]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# Spring RestClient — synchronous HTTP client baseline

> Layer: `raw/official-docs/` — Spring Framework reference "REST Clients" 페이지 + RestTemplate Javadoc 의 RestClient 정의 / WebClient·RestTemplate 비교 / 6.1 NOTE 발췌. ca-tmpl outbound Group G-C 의 대안 2 (RestClient baseline 채택) 의 1차 공식 근거.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-outbound-http-client-baseline]] | outbound HTTP baseline 으로 RestClient 채택 (sync default + WebClient extension + RestTemplate 회피) 근거 |
| [[raw/branch-notes/feature-integration-adapter-templates]] | adapter template 의 client 구성에서 `RequestInterceptor` / `ResponseErrorHandler` chain 의존 결정 근거 |

## 컨텍스트

ca-tmpl outbound HTTP baseline **"Spring RestClient"** 결정의 공식 근거. RestTemplate / WebClient 와의 위치를 명시.

## 출처 / Source

- Spring Framework Reference, "REST Clients": https://docs.spring.io/spring-framework/reference/integration/rest-clients.html
- RestTemplate Javadoc (current): https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/client/RestTemplate.html
- 아카이브 URL: (미수집)
- 저자 / 조직: Spring Framework (VMware/Broadcom)
- 발행일: rolling docs (확인 시점 Spring Framework 7.0.7)
- 마지막 확인일: 2026-05-27

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

> [§REST Clients — RestClient] "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."

> [§REST Clients — Choices for making calls to REST endpoints] "The Spring Framework provides the following choices for making calls to REST endpoints:" / "RestClient — synchronous client with a fluent API" / "WebClient — non-blocking, reactive client with fluent API"

> [§REST Clients — 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."

> [§REST Clients — RestClient] "For asynchronous and streaming scenarios, consider the reactive [WebClient]."

> [§RestTemplate Javadoc — NOTE] "NOTE: As of 6.1, `RestClient` offers a more modern API for synchronous HTTP access. For asynchronous and streaming scenarios, consider the reactive `WebClient`."

> [§RestTemplate Javadoc] "RestTemplate and RestClient share the same infrastructure (i.e. request factories, request interceptors and initializers, message converters, etc.), so any improvements made therein are shared as well."

> [§RestTemplate Javadoc] "However, `RestClient` is the focus for new higher-level features."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| RESTCLIENT-C1 | RestClient 는 **synchronous HTTP client** 이며 fluent API 와 HTTP library 추상화 + Java object 변환을 제공 | [§REST Clients — RestClient] "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+ sync HTTP 사용 | "sync" 가 단일 thread / blocking I/O 의 모든 detail (예: virtual thread 호환) 을 의미한다는 뜻은 아님 |
| RESTCLIENT-C2 | Spring Framework 가 공식으로 제공하는 REST endpoint 호출 선택지는 **2개** — `RestClient` (sync) 와 `WebClient` (non-blocking, reactive) | [§Choices] "The Spring Framework provides the following choices for making calls to REST endpoints:" + "RestClient — synchronous client with a fluent API" + "WebClient — non-blocking, reactive client with fluent API" | `official-vendor-doc` | Spring Framework 7.0+ 신규 코드 권장 | RestTemplate 가 사용 불가하다는 뜻은 아님 — deprecated 이지만 존재 |
| RESTCLIENT-C3 | **Spring Framework 7.0 에서 RestTemplate 는 deprecated** 되었으며, 향후 버전에서 제거 예정. RestClient 가 권장 마이그레이션 경로 | [§REST Clients — RestTemplate deprecation] "As of Spring Framework 7.0, `RestTemplate` is deprecated in favor of `RestClient` and will be removed in a future version" | `official-vendor-doc` | Spring Framework 7.0+ 환경 | 6.1 ~ 6.x 에서 RestTemplate 가 동일하게 deprecated 라는 뜻은 아님 (Javadoc 은 "maintenance" 뉘앙스의 NOTE 사용) |
| RESTCLIENT-C4 | RestTemplate Javadoc 은 **"As of 6.1, `RestClient` offers a more modern API for synchronous HTTP access"** 를 명시하며, async/streaming 은 reactive WebClient 권장 | [§RestTemplate Javadoc — NOTE] "NOTE: As of 6.1, `RestClient` offers a more modern API for synchronous HTTP access. For asynchronous and streaming scenarios, consider the reactive `WebClient`." | `official-vendor-doc` | Spring Framework 6.1+ 마이그레이션 판단 | Javadoc 의 "more modern" 이 자동 마이그레이션 가능을 의미하는 뜻은 아님 — API 차이 존재 |
| RESTCLIENT-C5 | RestTemplate 와 RestClient 는 **같은 infrastructure 공유** (request factory / interceptor / initializer / message converter) — 양쪽 개선이 공유됨 | [§RestTemplate Javadoc] "RestTemplate and RestClient share the same infrastructure (i.e. request factories, request interceptors and initializers, message converters, etc.), so any improvements made therein are shared as well." | `official-vendor-doc` | RestClient 마이그레이션 시 기존 ClientHttpRequestFactory / ClientHttpRequestInterceptor 재사용 | 두 API 의 시그니처가 동일하다는 뜻은 아님 — 호출 패턴 (fluent vs imperative) 이 다름 |
| RESTCLIENT-C6 | **RestClient 가 새로운 higher-level feature 의 focus** — RestTemplate 는 신규 기능 대상 아님 | [§RestTemplate Javadoc] "However, `RestClient` is the focus for new higher-level features." | `official-vendor-doc` | 향후 Spring HTTP client 기능 의존도 판단 | "RestTemplate 신규 기능 0개" 라는 뜻은 아님 — 명시는 focus shift |
| RESTCLIENT-C7 | reference 는 async/streaming 시나리오에서 reactive WebClient 사용을 권장 | [§REST Clients — RestClient] "For asynchronous and streaming scenarios, consider the reactive [WebClient]." | `official-vendor-doc` | sync vs reactive 분기 판단 | WebClient 가 모든 sync 환경에서 우월하다는 뜻은 아님 — [[outbound-webclient-vs-restclient-spring]] 의 `block()` 위험 별도 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `RESTCLIENT-C1` ~ `C7`: RestClient 정의, Spring 의 공식 2-선택지, 7.0 deprecation, 6.1 NOTE, 공유 infrastructure, focus shift, async/streaming → WebClient 권장
- **이 자료가 증명하지 않는 것**:
  - "As of 6.1, `RestTemplate` is in maintenance mode" 라는 **정확한 문구** — Framework 7.0.7 reference 페이지에는 "deprecated" 사용 (`RESTCLIENT-C3`), Javadoc 에는 "As of 6.1, `RestClient` offers a more modern API" 사용 (`RESTCLIENT-C4`). "maintenance mode" 라는 **문구 자체** 는 본 두 출처에서 확인 안 됨 — 이전 메모는 표현 변경된 인용
  - timeout 설정의 정확한 API (`JdkClientHttpRequestFactory` / `ReactorClientHttpRequestFactory` / `setConnectTimeout` / `setReadTimeout` / Duration) — 본 인용 범위 밖, 별도 페이지 확인 필요
  - `DefaultResponseErrorHandler` 의 4xx → `HttpClientErrorException` / 5xx → `HttpServerErrorException` 매핑 동작 — 본 인용 범위 밖
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 의 timeout 정책 (connect 2s / read 5s / call 10s) 을 RestClient 에 적용하는 정확한 builder 코드
  - error mapper 에서 `DEPENDENCY_*` 코드 변환 시 `ResponseErrorHandler` vs `onStatus` 의 선택
  - Spring Boot 3.x 의 RestClient auto-configuration (`RestClient.Builder` Bean 노출 여부)

## 메모 / Notes (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

- 세 client 의 위치 (Spring 7.0 기준, `RESTCLIENT-C3` + 6.1 NOTE 결합):
  - `RestTemplate` — **deprecated as of 7.0** (`RESTCLIENT-C3`). 신규 코드 권장 X.
  - `RestClient` — **sync 표준** (`RESTCLIENT-C2`, `C4`, `C6`). 신규 코드 default.
  - `WebClient` — async/streaming/reactive 필요할 때 (`RESTCLIENT-C7`).
- ca-tmpl 결정과의 매핑 (해석):
  - "기본 outbound HTTP 는 RestClient" ← Spring 공식 권장과 일치 (`RESTCLIENT-C4`).
  - "WebClient 는 별도 extension 문서" ← reactive 를 baseline 에 강제하지 않음 (`RESTCLIENT-C2` 의 2-선택지를 환경에 맞춰 분기).
  - "provider SDK bypassing mapper forbidden" ← RestClient 의 `RequestInterceptor` / `ResponseErrorHandler` chain 을 강제 경유 (`RESTCLIENT-C5` 의 infrastructure 공유 사실 기반 가정).
- timeout 설정 (ca-tmpl: connect 2s / read 5s / call 10s) 적용 방법 (해석 — 별도 출처 검증 필요):
  - Spring Boot 3.x: `ClientHttpRequestFactory` 에 `JdkClientHttpRequestFactory` 또는 `ReactorClientHttpRequestFactory` 사용.
  - `RestClient.builder().requestFactory(factory)` + factory 의 `setConnectTimeout` / `setReadTimeout`. "call timeout" 은 `JdkClientHttpRequestFactory` + `HttpClient` Duration 으로 별도 설정.
- 오류 매핑 (해석 — 별도 출처 검증 필요):
  - 기본 `DefaultResponseErrorHandler` 는 4xx → `HttpClientErrorException`, 5xx → `HttpServerErrorException`. ca-tmpl error mapper 에서 `DEPENDENCY_*` 코드로 변환해야 함.
- 시사점: RestClient 선택은 **공식 deprecation 정책과 일치**. RestTemplate 를 baseline 으로 두면 ca-tmpl 이 deprecated 위에 서는 문제 발생.

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/outbound-webclient-vs-restclient-spring]] — sync baseline vs reactive 선택의 별도 출처
  - [[raw/official-docs/outbound-openfeign-declarative-client]] — declarative 대안 배제 근거
  - [[raw/official-docs/outbound-resilience4j-vs-spring-retry]] — retry/circuit breaker library 비교
- 같은 주제 company-tech-blog:
  - [[raw/company-tech-blogs/outbound-stripe-rate-limit-retry-engineering]] — Stripe retry/backoff/idempotency 사례
- 인용하는 branch:
  - [[raw/branch-notes/feature-outbound-http-client-baseline]]
  - [[raw/branch-notes/feature-integration-adapter-templates]]
- 인용하는 wiki: (미작성)