donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
d71669eb596d920964bf3ec3d77ad07278b30d96
llm-wiki/raw/official-docs/outbound-spring-restclient-baseline.md
T

11 KiB
Raw Blame History

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

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

Reference in New Issue View Git Blame Copy Permalink