Files
clean-architecture-backend-…/docs/httpclient/repository-adaptation.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
2026-11-11 22:15:42 +09:00

7.8 KiB

HTTP Client 플랫폼 — 저장소 적응 계약

설계서: docs/design/2026-08-08-httpclient-platform-design.md 계획서: docs/history/plans/2026-08-08-httpclient-platform-implementation-plan.md

설계 패키지는 자기 적응 규칙을 스스로 밝힌다.

실제 Backend Skeleton 저장소가 제공되지 않았으므로 package 경로와 Gradle 구조는 설계서의 명시적 구현 가정이다. 구현 전 저장소의 기존 convention과 root package에 맞춰 경로만 조정하고 공개 계약과 정책 의미론은 유지한다.

이 파일은 설계가 가정한 배치를 이 저장소에 어떻게 옮겼는지 적은 유일한 기록이다. 바뀐 것은 경로, 빌드 DSL, 조립 루트의 소유뿐이다. 공개 계약, 정책 순서, 오류 의미는 명세대로 구현했다.

1. 모듈 배치가 다른 이유

설계는 modules/httpclient/ 아래에 Gradle 프로젝트 19개를 둔 새 라이브러리를 가정한다. 이 저장소는 Clean Architecture 템플릿이고, 닫힌 쪽으로 실패하는 registry(gradle/modules.json)가 Gradle 프로젝트 목록을 정한다. settings.gradle이 registry에 있는 프로젝트만 포함하고, verifyCleanArchitectureDependencies가 허용하지 않은 의존을 막는다. leaf 목록은 registry가 정본이다. 설계의 모듈마다 Gradle 프로젝트를 만들면 AGENTS.md의 HARD-STOP 5번(registry·Gradle 의존성 검증 위반)에 걸린다.

그래서 설계의 라이브러리 모듈은 등록된 leaf :adapter:outbound:httpclient 안의 package 경계가 된다. 이 저장소 자신의 규칙 때문에 예외가 둘 있다.

설계 모듈 저장소 위치 이유
httpclient-spring-boot-starter :adapter:outbound:httpclient(dev.caskeleton.adapter.outbound.httpclient.autoconfigure) capability 전용 Spring 조립은 재사용하는 HTTP client 플랫폼과 함께 둔다. app-bootstrap은 capability를 고르고 포함할 뿐이고, 런타임 활성화는 app.httpclient.enabled로 남는다.
httpclient-testkit :adapter:outbound:httpclient src/testFixtures/java/**/testkit 설계는 production 모듈이 testkit에 의존하는 것을 금한다. Gradle testFixtures는 재사용 테스트 지원을 테스트 소비자에게만 내놓는다. 보통 테스트, integration/performance lane, JMH는 그 면을 명시적으로 골라 쓰고 production에는 드러나지 않는다. PlatformClasses는 test-fixture 출력을 빼서 경계 규칙이 계속 production 클래스만 뜻하게 한다.

package 경계는 설계의 모듈 의존 표를 재현한 ArchUnit 규칙(PublicApiArchitectureTest, HttpClientModuleBoundaryTest)이 강제한다.

2. Package 대응

Root package: io.backend.skeleton.httpclient → dev.caskeleton.adapter.outbound.httpclient.

설계 모듈 설계 package 저장소 package
httpclient-core-api …httpclient.api (+ .body, .error, .operation, .result) dev.caskeleton.adapter.outbound.httpclient.api (+ 같은 하위 package)
httpclient-profile …httpclient.profile …outbound.httpclient.profile
httpclient-transport-spi …httpclient.transport …outbound.httpclient.transport
httpclient-transport-apache …httpclient.apache …outbound.httpclient.apache
httpclient-transport-jdk …httpclient.jdk …outbound.httpclient.jdk
httpclient-restclient …httpclient.restclient …outbound.httpclient.restclient
httpclient-resilience …httpclient.resilience …outbound.httpclient.resilience
httpclient-auth …httpclient.auth …outbound.httpclient.auth
httpclient-security …httpclient.security …outbound.httpclient.security
httpclient-observability …httpclient.observation …outbound.httpclient.observation
httpclient-transport-reactor-netty …httpclient.reactor 지움(결정 9, 2026-09-25: blocking만)
httpclient-webclient …httpclient.webclient 지움(결정 9, 2026-09-25: blocking만)
httpclient-service-client …httpclient.service …outbound.httpclient.service
httpclient-dynamic-target …httpclient.dynamic …outbound.httpclient.dynamic
httpclient-jetty-http3-experimental …httpclient.http3 …outbound.httpclient.http3
httpclient-spring-boot-starter …httpclient.autoconfigure dev.caskeleton.adapter.outbound.httpclient.autoconfigure
httpclient-testkit …httpclient.testkit …outbound.httpclient.testkit (testFixtures source set)

3. 그 밖에 일부러 바꾼 것

설계 가정 저장소 현실 적응
Gradle Kotlin DSL, build-logic convention plugin Groovy DSL, root build.gradle convention, LockMode.STRICT 의존성 잠금 의존성은 src/adapter/outbound/httpclient/build.gradle에 선언하고 gradle.lockfile을 다시 만들었다.
Spring Framework 6.2 기준, 7.0 호환 저장소 기준은 Spring Boot 4.0 계열 / Spring Framework 7.0이다. 정확한 버전은 gradle/libs.versions.toml의 springBoot다 공통 코드는 Spring 6.2 API 면을 대상으로 한다(공통 package에 6.2 전용이나 7.0 전용 클래스가 없다). Spring 7 HTTP Service Group 통합과 RestTemplate 이전 package는 지웠다.
settings.gradle.kts 모듈 등록 닫힌 쪽으로 실패하는 registry registry는 바꾸지 않았다. leaf 식별자, gradle path, 허용 의존은 그대로다.
설계 §6.2는 Apache HttpClient 5를 HTTP/2 가능으로 등급 매긴다 Spring의 blocking factory는 Apache의 classic client를 쓰고, 그것은 HTTP/1.1만 한다. HTTP/2는 Apache의 async client에 있다 ApacheBlockingTransportProvider는 HTTP/1.1을 선언하고 HTTP/2 profile을 시작 때 거부한다. blocking HTTP/2는 JDK transport가 맡고, NegotiatedProtocolContractTest가 잰다.
설계 §28.1은 상태 있는 fixture로 WireMock을 든다 WireMock의 Jetty 모듈은 이 모듈이 HTTP/3 때문에 이미 쓰는 Boot 관리 Jetty 12와 ABI가 달라 서버 시작에서 실패한다 StatefulUpstream이 기존 fixture 서버 위에서 경로별 상태 있는 응답을 준다. shaded jar로 돌아가지 않고 WireMock 의존성을 지웠다
작업마다 git commit AGENTS.md: 커밋 정책은 human-only 구현은 stage하지 않은 채 넘겼고, 커밋은 사람이 했다. 계획 중 일부러 실행하지 않은 단계는 이것 하나이고, 여기 적어 둔다.
docs/httpclient/**, httpclient workflow, scripts/verify-httpclient-docs.py 저장소가 이미 docs/와 workflow 폴더를 가진다 같은 저장소 상대 경로에 만들었다. httpclient 전용 workflow 파일은 2026-11-08 단계 파일 셋(.gitea/workflows)의 job으로 접었다.

4. 설계에서 바뀌지 않은 것

  • H1 / H2 / H3 / H4 노출 규칙과 금지한 native 엔진 시그니처.
  • ExecutionEvidence, BodyReplayability, OperationIdempotency, AttemptStage, FailureCategory.
  • HttpOperation, HttpCallResult, BodySource, ResponseType, BlockingStreamingResponse.
  • 안정된 예외 계층 전체와 HttpFailureMetadata 가리기 규칙.
  • Named Client Profile schema, 시작 검증 코드, 연산 덮어쓰기 방향.
  • 실제 기한 공식, 시도 예산, 스트리밍의 준비/idle 분리.
  • 재시도 자격 입력, 순서 있는 판정 표, 재시도 예산, backoff 규칙.
  • Circuit → Rate Limiter → Bulkhead 시도 순서와 논리 허가 위치.
  • OAuth2 cache key, 한 번만 날아가는 갱신, 401 재전송은 많아야 한 번이라는 규칙.
  • TLS 허용/금지 목록과 영구 실패 분류.
  • Dynamic Target 정규화 → 모든 DNS 답 검증 → 고정 → redirect 재검증.
  • 가짓수가 적은 tag 허용 목록, 금지 label, trace와 로그 규칙.
  • 런타임 세대 교체와 drain 의미.