donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
6c53ded9cb70f2d7cf3e66ff50d42f2d151c98b1
llm-wiki/vault/20-evidence/official-docs/spring-restclient-builder-reference.md
T

11 KiB
Raw Blame History

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

핵심 인용 / 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 / 관련

Reference in New Issue View Git Blame Copy Permalink