Files
clean-architecture-backend-…/docs/httpclient/performance-baseline.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

3.0 KiB

HTTP Client 플랫폼 — 성능 기준선

인증 lane은 처리량 목표가 아니라 자원 상한을 단언한다. 실패하는 upstream, 큰 본문, 교체가 메모리, connection, 스레드, upstream 트래픽을 끝없이 먹지 못함을 증명하려는 것이다. 여기 있는 어떤 것도 실행 중 적응형 기본값이 되지 않는다. 모든 상한은 profile에 명시한 설정에서 온다.

돌리는 법

# 모든 상한: 구조적 상한과 기계에 따른 상한
./gradlew :adapter:outbound:httpclient:httpClientPerformanceTest --console=plain

# JMH benchmark: 숫자만 낸다. 게이트가 아니다
./gradlew :adapter:outbound:httpclient:jmh --console=plain

lane은 매번 모든 상한을 단언한다. 기계에 따라 다른 상한을 끄는 스위치는 없다. 빌드가 performance.assertions.enabled에 true 아닌 값을 넣으면 strict lane convention이 성능 lane을 돌기 전에 실패시키고, 테스트 하나라도 건너뛰면 실패시킨다. integration-main.yml(:performanceCheck)과 release.yml이 도는 것도 같은 명령이다. 매번 잰 heap 증가량([httpclient-performance] streaming download heap increase … bytes, bound … bytes)을 테스트 출력과 보고서에 찍고, 실패한 상한은 단언 메시지에 그 값을 다시 적는다. 판정 없는 숫자가 필요하면 JMH를 쓴다.

인증한 상한

테스트 상한 종류
RetryStormBudgetTest 실패하는 upstream에 대한 논리 호출 10 000개가 10 % 예산에서 물리 시도를 최대 11 000개 만든다 구조적
LargeBodyResourceTest 32 MiB 스트리밍 다운로드가 payload를 heap에 버퍼링하지 않고 모든 바이트를 읽는다 구조적 + 기계에 따른 heap 상한
PoolSaturationPerformanceTest connection 4개짜리 pool에 대한 동시 호출 24개가 모두 끝 상태에 닿는다. 멈춘 것이 없다 구조적
OAuthRefreshContentionTest 정말 동시에 부르는 호출자 100개가 token 요청을 정확히 하나 만든다 구조적
RuntimeRotationDrainTest 교체 50번이 내린 세대 50개를 모두 닫고 drain 스레드를 남기지 않는다 구조적

기준선 기록하기

배포를 인증할 때는 숫자와 함께 이것을 적는다: 정확한 명령, commit, 하드웨어, JVM flag, 시험한 profile YAML, p50/p95/p99/max, 최대 heap, 최대 direct memory, 스레드 수, connection 수, 물리 시도 수, 오류 수. profile과 하드웨어 없는 지연 숫자는 기준선이 아니라 일화다.

항목 값
명령 인증할 때 채운다
Commit 채운다
하드웨어 / JVM 채운다
시험한 profile 채운다
p50 / p95 / p99 / max 채운다
최대 heap / direct memory 채운다
스레드 / connection 채운다
물리 시도 / 오류 채운다

이 표는 저장소에서 일부러 비워 둔다. 빌드 agent에서 잰 숫자를 인증한 기준선처럼 내놓는 것은 기준선이 없는 것보다 나쁘다.