Files
clean-architecture-backend-…/docs/httpclient/support-matrix.md
T
DongHyeonka e38c949c2f docs(httpclient): HTTP client 문서를 한국어로 옮기고 숫자 복사를 없앤다
문제: docs/httpclient 아래 살아 있는 문서 9개가 영어였다(language 예외).
repository-adaptation.md는 registry의 leaf 수를 「exactly 19 leaf identities」로, Spring
Boot 버전을 4.0.8로 옮겨 적었다(number 예외 두 줄). 같은 문서가 testkit을 `testkit`
source set이라고 했지만 1절 표와 실제 코드는 `testFixtures`다.

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·예외·metric·위반 코드·표 구조는
원문으로 둔다. scripts/verify-httpclient-docs.py가 코드에서 뽑는 이름이 모두 문서에 남는다.
leaf 수는 registry(src/config/architecture/modules.json)를, 버전은
src/gradle/libs.versions.toml의 `springBoot`를 가리킨다. 등급 이름(Stable, Default,
Restricted, Internal, Experimental)은 꼬리표라 원문으로 둔다. env-fields.yaml은 머리 주석만
옮겼다. HttpClientPlatformEnvManifestTest는 주석을 읽지 않는다(`- field:`·`env:` 줄만).
configuration-reference.md의 「Three of these」 뒤 목록이 다섯이라 「아래 코드들」로 고쳤다.

버린 대안: 리뷰 번호(RR-03-14 등)를 걷어 내기. 이 작업은 번역이고 내용 감사는 다음 리뷰 몫이라
날짜와 함께 그대로 둔다.

위험·한계: 내용 감사는 하지 않았다.

검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0).
python3 scripts/verify-httpclient-docs.py PASS(코드에서 뽑은 이름 156개 모두 문서에 있음).
2026-11-07 17:29:57 +09:00

6.2 KiB

HTTP Client 플랫폼 — 지원 매트릭스

등급은 설계서 §6과 §29를 따른다. 행이 Stable이려면 transport를 넘는 계약 suite가 그것을 증명해야 한다. suite가 증명하지 못하는 것은 Experimental이고 그렇다고 밝힌다. 등급 이름(Stable, Default, Restricted, Internal, Experimental)은 원문 그대로 쓴다.

Spring API

API 등급 역할 제약
RestClient Stable blocking 실행(유일한 실행 모델) 동시성 상한과 실제 기한이 필수다
HTTP Service Client(@HttpExchange) Default 선언형 타입 있는 client 연산 metadata가 필수다
Generic Exchange (H2) Restricted 동적 method, 경로, 본문 Base URL과 정책은 바꿀 수 없다
Dynamic Target (H3) Restricted 사용자가 준 URL 따로 된 SSRF 정책. credential을 물려받지 않는다
Native 엔진 Internal 엔진별 설정 애플리케이션이 쓰는 API가 절대 아니다

Transport

플랫폼은 blocking만 한다(결정 9, 2026-09-25). 모든 호출은 호출자의 스레드(이 템플릿에서는 virtual thread)에서 RestClient를 거쳐 돈다. reactive 실행 경로도, WebClient도, Reactor Netty transport도 없다.

Transport HTTP/1.1 HTTP/2 HTTP/3 등급 확인하는 것
Apache HttpClient 5 (classic) 된다 안 된다 안 된다 Stable(기본) httpClientStableContractTest, NegotiatedProtocolContractTest
JDK HttpClient 된다 된다(TLS/ALPN) 안 된다 Stable(가벼움, HTTP/2) NegotiatedProtocolContractTest
Jetty 된다 된다 된다 Experimental Http3OptInTest뿐
Simple request factory 제한적 안 된다 안 된다 로컬 테스트 전용 운영에서는 ClientProfileValidator가 거부한다

여기서 Apache가 HTTP/1.1인 이유

설계서 §6.2는 Apache HttpClient 5를 HTTP/2 가능으로 등급 매긴다. 라이브러리는 그렇다. 다만 async client에서다. Spring의 HttpComponentsClientHttpRequestFactory는 classic client를 쓰고, 그것은 HTTP/1.1만 한다. NegotiatedProtocolContractTest는 이것을 가정하지 않고 잰다. classic client는 prior-knowledge h2c 서버에 대해 바로 실패한다.

그래서 ApacheBlockingTransportProvider.capabilities()는 HTTP/1.1을 선언한다. Apache와 HTTP_2를 짝지은 profile은 이 표가 다르게 주장하는 동안 조용히 HTTP/1.1로 도는 대신 시작 때 거부된다. HTTP/2는 JDK transport가 맡는다. 설정에서 읽지 않고, 실제 TLS handshake 뒤 client 쪽에서 잰다. HTTP/2만으로 제한할 수 있는 transport는 없으므로 HTTP_2만 선언한 profile은 거부한다(HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED).

JDK transport는 routeScopedPool=false, boundedPendingAcquireQueue=false, dynamicTargetStable=false를 선언한다. 그중 하나라도 필요한 profile은 약한 보장으로 돌지 않고 시작 때 거부된다. 그래서 Apache와 JDK 사이의 선택은 진짜 맞바꿈이다. Apache는 route 범위 pool과 Dynamic Target 고정을 주고, JDK는 HTTP/2를 준다.

Capability 관문

Capability 관문
Dynamic Target (H3) Apache만. JDK와 Jetty는 거부한다
HTTP/3 experimentalAcknowledgement가 I_ACCEPT_HTTP3_EXPERIMENTAL_SEMANTICS와 같아야 한다
origin을 넘는 redirect profile마다 골라 켠다. hop에서 credential을 지운다
재시도 증거 기반. HTTP method만으로 켜지지 않는다

CI 매트릭스

Profile 빈도 릴리스 게이트 Task
Spring Framework 7.0(저장소 기준) 이 leaf를 건드린 PR, main push, 릴리스 필수 spring70CompatibilityTest
Spring Framework 6.2 API 면 모든 PR(check), 릴리스 필수 spring62ApiSurfaceScan
Apache HC5 + RestClient 이 leaf를 건드린 PR(두 transport는 check로 모든 PR에서 함께 돈다), 릴리스 필수 httpClientStableContractTest -Phttpclient.contract.transports=apache
JDK HttpClient + RestClient 이 leaf를 건드린 PR(두 transport는 check로 모든 PR에서 함께 돈다), 릴리스 필수 httpClientStableContractTest -Phttpclient.contract.transports=jdk
SSRF / 가짓수 suite 모든 PR(check), 릴리스 필수 httpClientSecurityTest
Toxiproxy 장애 suite main push, nightly(integrationCheck), 릴리스 필수 httpClientFailureInjectionTest
성능 인증 main push, nightly(performanceCheck), 릴리스 필수 httpClientPerformanceTest(모든 상한을 단언. 끄는 스위치가 없다)
Jetty HTTP/3 main push, nightly Experimental, 막지 않음 test -Phttp3.tests.enabled=true

Spring 6.2 lane의 알려진 한계

이 저장소의 Spring Boot 4.0 기준은 Spring Framework 7을 고정한다. 그래서 여기서는 실제 6.2 런타임을 풀 수 없다. spring62ApiSurfaceScan은 대신 API 면을 확인한다. 공통 package가 Spring 7 전용 타입을 참조하지 않아야 하고, 어떤 클래스도 org.springframework.web.service.registry를 쓰지 않아야 한다. 실제 6.2 배포판에 대해 suite를 돌리려면 그 계열의 host 프로젝트가 필요하다. 이 한계는 통과하는 검사 뒤에 숨기지 않고 밝혀 둔다.

Suite가 증명하지 않는 것

매트릭스를 바람이 아니라 측정으로 읽게 하려고 적는다.

빈곳 이유 대신 증명하는 것
HTTP/2 frame 주입(REFUSED_STREAM, 임의 GOAWAY) fixture 서버에 frame 수준 제어가 없고, 전용 h2 서버는 여기서 얻는 보장보다 큰 의존성이다 Http2EvidenceMapperTest가 frame → 증거 대응을, NegotiatedProtocolContractTest가 h2가 정말 협상되는지를 증명한다
Spring 6.2 런타임 이 저장소의 Boot 4.0 기준이 Spring 7을 고정한다 spring62ApiSurfaceScan이 공통 package를 6.2 API 면 안에 가둔다
성능 지연 기준선 빌드 agent에서 잰 숫자는 인증이 아니다 httpClientPerformanceTest가 매번 구조적 상한과 스트리밍 heap 상한을 단언한다. 지연 숫자는 단언하지 않는다