Files
clean-architecture-backend-…/docs/httpclient/repository-adaptation.md
T
DongHyeonka d46bab9659
pr / gradle (pull_request) Successful in 16m42s
pr / vulnerabilities (pull_request) Successful in 37s
pr / done (pull_request) Canceled after 0s
ci!: workflow를 pr·main·release 셋으로 접고 단계 job 모양만 검사한다
workflow 15개(+ composite action, jq 설치 스크립트)가 모듈 모양으로
나뉘어 있었고, 그것을 읽는 판독기(ShellScript·WorkflowGradleInvocations·
TaskSelectors, 운영 3,283줄과 그 시험 1,814줄)가 리뷰 라운드마다 새 셸
모양으로 결함을 냈다. 그런데 Gitea에서는 Actions가 꺼져 있어 workflow는
한 번도 돌지 않았다(design-docs repo-structure/03-ci.md 2.1·3.4절).

소유자가 정한 B안(같은 문서 7절, 11절 ①~⑧)대로 바꾼다.

- .gitea/workflows/pr.yml: `gradle` job이 `./gradlew :prCheck`와
  `./gradlew :verifyStrictLaneStages --dry-run` 두 줄, `vulnerabilities`
  (trivy), 필수 검사 하나 `done`.
- main.yml: push마다 mainCheck·integrationCheck·build-logic 시험·
  configuration cache·lychee·trivy·http3(권고). nightly·수동 실행에서
  PostgreSQL major·HTTP transport·Redis topology 행렬, NFS, 알림 chaos,
  jpa-next, compose smoke, 마지막에 `needs`로 performanceCheck.
- release.yml: releaseCheck와 기존 release lane, 이미지를 이 Gitea
  레지스트리에 올리고 cosign 키 쌍으로 서명한다. 수동 실행은 push·서명
  앞까지 돈다. upload/download-artifact를 쓰지 않는다. JPA 승격은
  `needs: jpa-release-gate`가 대신한다.
- 새 집계 `prCheck` = ci + verifyDependencyLocks + compose 렌더링 +
  저장소 배치 + 문서 검사(Exec). workflow와 verify.sh가 같은 한 줄을 쓴다.
- verifyStrictLaneStages: 그래프 검사(모든 strict lane이 선언한 단계의
  계획에 있다)는 그대로 두고, workflow 쪽은 고정 문자열 형식 검사로
  바꾼다. 단계마다 workflow·이벤트·필터·job·옵션·조건을 build.gradle에
  선언하고, 그 job의 step이 `run: ./gradlew <단계> <옵션>`을 가지며 다른
  run도 셸 문법 없는 ./gradlew 한 줄이고, 선언 밖의 if:, 조건 없는
  needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 다른
  working-directory, 선언 밖의 이벤트 필터가 없는지 본다. PR 단계 job
  하나는 이 검사 자신을 돌려야 한다. 셸 해석 코드와 그 시험을 지운다
  (build-logic 운영 코드 −3,167줄, 시험 −2,231줄). 우회 입력 21가지를
  TestKit 시험으로 둔다.
- scripts/verify.sh <단계>: 사람·세션의 진입점. 무거운 단계는 지금 작업
  트리를 패치로 desktop에 보내 잠금 아래에서 돌린다(operate.md 4.1절의
  손 절차). scripts/ci/는 workflow가 부르는 trivy·Redis topology·포트
  포워더·configuration cache 스크립트다.
- workflow를 읽는 시험(DeveloperExperienceContractTest, JpaRelease
  RenderingTest, FileserverDocumentationCoverageTest)과 입력 선언을
  .gitea로 옮기고, keyless 서명 시험을 키 쌍 서명 시험으로 바꾼다.
- 문서: gates.md·operate.md·docs/ci-cd·AGENTS.md(검증 절)·build-logic
  AGENTS.md(셸 규칙 문단을 세 줄로)·leaf 문서의 workflow 참조,
  docs/upgrade B-57~B-61.

버린 것: workflow 하나에 if:로 단계를 나누기(파일만 보고 단계를 알 수
없다), 레지스트리에서 생성(같은 정보의 셋째 사본), 바뀐 모듈만 돌리기
(결정 30과 충돌). 판독기를 남기고 고치기는 6라운드 13건이 반증했다.

위험: PR이 어댑터 컨테이너 lane과 Redis standalone lane을 더는 막지
않는다(main·nightly에서 빨갛게 된다. 소유자 결정 ②). main push는 ci를
다시 돌리지 않는다. 성능 lane은 매 push가 아니라 nightly에서만 돈다.
`.github/workflows/messaging-certification.yml`은 메시징 분리 작업이
지우므로 남겼다(.gitea가 있으면 Gitea가 읽지 않는다). 서명·push는 secret이
없어 실제 태그로는 돌려 보지 않았다.

BREAKING CHANGE: workflow 파일 위치와 이름, strictLaneStages 문법,
릴리스 레지스트리·서명 방식이 바뀌었다. docs/upgrade/2026-11-maturity-
review.md B-57~B-61을 따른다.
2026-11-08 21:55:43 +09:00

7.9 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(src/config/architecture/modules.json)가 Gradle 프로젝트 목록을 정한다. src/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이다. 정확한 버전은 src/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 의미.