DongHyeonka 416d882471 fix(httpclient): JDK 시도가 deadline 직전에 끊겨 응답 timeout으로 보고되지 않게 한다
문제:
JDK transport는 attempt deadline을 Spring JdkClientHttpRequest의 read
timeout 하나로 끊는다. DeadlineAwareJdkRequestFactory는 그 값을
AttemptDeadline.bound(response-header)로 정하고, bound는 남은 시간을
나노초까지 그대로 돌려준다. Spring 7.0.9 TimeoutHandler는 이 값을
Duration.toMillis()로 잘라 timer를 건다. 그래서 timer가 deadline보다
최대 1ms 먼저 터진다.

BlockingAttemptExecutor.finish와 circuit breaker 제외 조건
(deadline.setByCaller() && scope.expired())은 엔진이 포기한 뒤에
scope.expired()로 deadline이 원인인지 묻는다. 그 순간 deadline은 아직
지나지 않았다. 그래서 호출자 deadline으로 끊긴 시도가
HttpResponseTimeoutException(헤더 대기 중)이나
HttpResponseTruncatedException(본문 중)으로 보고되고, breaker는 그것을
상대 장애로 센다. 건강한 상대 서버에 circuit이 열릴 수 있다.
CircuitBreakerStatusAccountingTest의 JDK 변형 2건이 이 경로로 실패했다.

고른 방법:
bound가 남은 시간으로 줄인 값을 다음 밀리초로 올린다. 엔진 timer는
bound를 계산한 뒤에 걸리므로, 올린 값을 밀리초로 잘라 건 timer도
deadline보다 먼저 끝나지 않는다. 단계 timeout이 더 짧으면 그 값을 그대로
둔다.

버린 대안:
- JDK 일반 요청도 scope abort로 끊기(Apache·Jetty 방식). Spring 요청의
  응답 future에 닿을 수 없어 JdkClientHttpRequest를 본문 닫기까지 다시
  구현해야 한다. 결함 크기에 비해 바뀌는 면이 크다.
- finish에서 1ms 여유를 두고 deadline으로 판정. deadline 근처에서 터진
  진짜 단계 timeout도 deadline으로 바꿔 부르는 추측이다.
- factory에서만 올리기. bound를 쓰는 다음 엔진이 같은 함정에 빠진다.

위험·한계:
- deadline으로 줄인 JDK timer는 deadline보다 1ms 미만 늦게 끝난다.
  JDK 일반 요청이 deadline을 넘기는 시간이 그만큼 늘어난다.
- 같은 원인을 찾아본 곳: JDK 스트리밍 setup(JDK 요청 timeout은 나노초를
  지키고 deadline은 scope abort가 끊는다), Apache·Jetty(scope abort가
  fired를 먼저 세운다), messaging DefaultMessagePublisher.withDeadline
  (밀리초로 자르지만 원인을 TimeoutException 타입으로 판정한다),
  gRPC·Redis(나노초 단위). 같은 원인은 없었다.

검증(desktop, 공유 잠금 아래, 로그 ~/t2-cb-logs/):
- RED: 기준 커밋 06f520e6에 새 테스트만 얹고
  CircuitBreakerStatusAccountingTest·AttemptDeadlineTest를 --rerun으로
  10회. 10/10 rc=1. 새 단위 테스트 10/10 실패, CircuitBreaker JDK
  변형은 10회 중 9회 실패(JDK 케이스 20건 중 14건).
- GREEN: 수정 트리에서 같은 명령 10회 두 번. 20/20 rc=0, 실패 0.
- ./gradlew ci: rc=0(93초, 다른 leaf는 캐시 재사용, httpclient test
  359건·계약 23건·보안 9건·Spring 6.2 스캔 7건 실제 실행).
- :adapter:outbound:httpclient:testQualityCheck spring70CompatibilityTest
  (23건) rc=0, httpClientFailureInjectionTest(Toxiproxy, 4건) rc=0.

Fixes: 34565130e0 ("fix!: 성숙도 리뷰의 High·P1 결함 19건을 고친다")
2026-11-06 22:01:08 +09:00

ca-skeleton — Clean Architecture Spring Boot 템플릿

ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 dev.caskeleton이며, 예시 도메인은 production 모듈이 아니라 sample-portfolio 모듈(WorkLog 작업 기록 게시판)에 격리합니다.

이 문서는 전체 구조와 첫 실행만 다룹니다. 모듈별 상세 규칙과 설계 근거는 각 모듈의 README와 CLAUDE.md가, 빌드·환경 변수 상세는 src/README.md가 소유합니다.

아키텍처 한눈에

의존은 항상 바깥에서 안으로 흐릅니다. adapter가 core의 port에 의존하고, core는 adapter를 알지 못합니다. 이 방향이 유지되는 한 도메인 규칙과 기술 선택(웹 프레임워크, DB, 메시징)을 서로 독립적으로 바꿀 수 있습니다.

app-bootstrap -> adapter:inbound:*  -> application-core -> domain-core
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
모든 런타임 모듈 -> shared-contract
sample-portfolio -> 등록된 런타임 리프 (fixture 소비자 전용)

family 수준의 책임은 다음과 같습니다.

모듈 family 책임
domain-core 순수 도메인 모델·불변식·이벤트·port. 프레임워크·transport·DB·IO 타입 금지
application-core command·유스케이스·application 정책·트랜잭션 port. inbound DTO·persistence entity 금지
adapter:inbound:* HTTP·gRPC·GraphQL·WebSocket transport 경계, DTO·validation·인증·에러 매핑
adapter:outbound:persistence-* JPA/PostgreSQL·MongoDB 영속 구현과 매핑·migration
adapter:outbound:* support(공유 베이스)·messaging·cache·notification·object storage·file·HTTP client·identifier 능력을 port 뒤에서 구현. 기본 조립에는 support·identifier만 들어 있고, 나머지는 app-bootstrap/build.gradle의 runtimeOnly 한 줄로 고릅니다
shared-contract skeleton 전역 운영 계약. business/domain 개념 저장 금지
app-bootstrap Spring Boot entrypoint와 composition root
sample-portfolio WorkLog 예시 도메인(fixture/reference). production이 의존하지 않음

등록된 leaf 목록과 각 leaf의 Gradle path·소스 경로·허용 production 의존 edge는 src/config/architecture/modules.json이 SSOT입니다. focused test는 해당 Gradle path에서 ./gradlew <gradle-path>:test --console=plain 형태로 파생하며, root 문서나 기억에서 개별 leaf edge를 추론하지 않습니다.

퀵스타트

전제조건은 Temurin 21(루트 .tool-versions에 고정)과 Docker Engine 또는 Docker Desktop입니다. Gradle은 저장소 wrapper를 씁니다. 첫 실행 진입점은 하나입니다.

scripts/bootstrap-local.sh          # 다른 Compose overlay는 scripts/bootstrap-local.sh <profile>

scripts/bootstrap-local.sh는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, GET /api/healthcheck HTTP smoke를 순서대로 실행합니다. 각 단계가 bootstrap N/4 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.

curl -fsS http://localhost:8080/api/healthcheck

로컬 스택을 내릴 때는 저장소 루트에서 실행합니다.

docker compose -f docker-compose.yml -f docker-compose.local.yml down

src/.env.example은 배포 환경 변수의 추적 가능한 복사/검증 계약이고 src/.env는 로컬 실행 입력입니다. 전체 환경 변수 목록과 조정 시점은 src/README.md와 docs/registries/env-keys.yaml에 있습니다.

기본 조립과 부가 기능

기본 조립(bootJar)은 web, 관측, domain-core·application-core·shared-contract, support, identifier뿐이라 DB·Redis·Kafka 없이 기동합니다.

cd src
./gradlew :app-bootstrap:bootRun

DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능은 app-bootstrap/build.gradle에 주석 처리된 runtimeOnly 한 줄씩으로 있습니다. 줄의 주석을 풀고 필요한 env를 넣으면 켜지고, 줄을 지우면 사라집니다. 줄마다 필요한 env와 끄는 키는 src/README.md의 "기능 추가 = 한 줄 + env" 표에 있습니다.

프로파일 데이터스토어 (persistence-jpa 줄을 넣었을 때) 스키마 소유자
local Compose PostgreSQL (./gradlew :app-bootstrap:bootRunH2는 줄 없이도 모듈을 자기 classpath에 올려 H2 in-memory로 실행) Flyway (H2는 Hibernate create-drop)
dev PostgreSQL Flyway
prod PostgreSQL Flyway

H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 vendor 동작은 검증하지 않습니다. 프로파일별 설정은 src/app-bootstrap/src/main/resources/의 application-{local,dev,prod}.yml이, 상세 설명은 src/README.md가 소유합니다.

새 프로젝트로 시작하기

이 저장소를 새 서비스의 출발점으로 쓸 때 핵심 단계는 다음과 같습니다. 전체 체크리스트는 AGENTS.md의 "템플릿 재사용 체크리스트"에 있습니다.

  1. src/settings.gradle의 rootProject.name을 새 서비스 이름으로 바꿉니다.

  2. 패키지 루트 dev.caskeleton을 조직·서비스 패키지로 바꿉니다. 소스뿐 아니라 빌드·설정 파일의 참조도 함께 바꿔야 mainClass·group이 어긋나 bootstrap이 깨지지 않습니다.

    cd src
    find . -type f \( -name '*.java' -o -name '*.gradle' -o -name '*.yml' \) -print0 | xargs -0 sed -i 's/dev.caskeleton/com.yourorg.yourservice/g'
    

    애플리케이션 이름 등 나머지 rename 단계는 위 체크리스트를 따릅니다.

  3. CaSkeletonApplication을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 예시 코드는 sample-portfolio에만 둡니다.

  4. 모듈 이름과 경계는 그대로 유지합니다.

검증은 먼저 composition root의 빠른 테스트와 sample-off 계약을 확인합니다. 루트에서 ./gradlew test를 호출하면 등록된 모든 하위 프로젝트의 test를 실행하므로 일상적인 로컬 피드백 명령으로 사용하지 않습니다. 저장소 전체 qualification은 CI 또는 명시적인 ci task가 담당합니다.

cd src
./gradlew :app-bootstrap:test
./gradlew :sample-portfolio:check
./gradlew architectureCheck

병합 전 저장소 전체 검증이 필요하면 ./gradlew ci를 실행합니다.

sample-portfolio는 템플릿이 유지하는 fixture/reference 모듈이라 production 모듈이 의존하지 않고, runtime에 sample bean이나 endpoint를 넣지 않습니다. 다운스트림 fork에서 fixture가 더 필요 없을 때만 sample-off 테스트를 통과시킨 뒤 정리합니다.

아키텍처 규칙과 검증

애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. HARD-STOP 7개 조건의 정본 로컬 정책 권위는 AGENTS.md이며, CLAUDE.md는 작업을 시작할 때 읽는 지도입니다. 일의 종류별 절차는 docs/work/에 있습니다.

  • domain-core는 Spring·JPA·Servlet·HTTP·DB·cloud SDK 타입을 import하지 않습니다.
  • controller는 repository를 직접 호출하거나 persistence entity를 반환하지 않습니다.
  • inbound DTO는 application-core나 domain-core로 들어가지 않습니다.
  • 비즈니스 정책은 mapper·filter·config·settings·controller에 두지 않습니다.
  • 새 외부 시스템 연동은 domain/application port와 adapter 모듈로 표현합니다.

이 규칙은 두 축으로 자동 강제합니다. :app-bootstrap:architectureTest의 분할된 ArchUnit 규칙들이 컴파일된 소스 의존성을, verifyCleanArchitectureDependencies 게이트가 JSON registry의 허용 Gradle project edge를 검사합니다.

cd src
./gradlew verifyCleanArchitectureDependencies

두 검증 축은 ci-quality-gates.yml의 release gate에 연결되어, 규칙 위반이 병합·릴리스를 막습니다.

수동 전용 Gradle 태스크

아래 세 태스크는 어떤 워크플로도 실행하지 않으며, 그게 의도다. 자동 실행이 틀린 이유를 각각 적어 둔다.

여기 적힌 태스크 이름이 실재하는지 검사하던 verifyReadmeCommands는 삭제했다. 그건 이 문서의 ```bash 블록을 직접 파싱해 ./gradlew·docker compose·make 토큰을 실제 태스크 그래프와 대조하는 Markdown 명령 파서였고, 그 결과 "README에 무엇을 쓸 수 있는가"가 그 파서가 읽을 수 있는 문법의 함수가 됐다. 문서와 코드가 어긋나는 것은 결함이지만, 빌드를 실패시켜서 고칠 일은 아니다.

cd src
./gradlew :grpc:grpc-testkit:grpcPerformanceTest
./gradlew :sample-portfolio:openapiCheckSnapshot -PapproveOpenApiChange
  • grpcPerformanceTest — latency percentile·saturation·drain budget을 측정한다. 공유 CI runner의 측정값은 흔들리고, 흔들리는 게이트는 결국 꺼진다. leaf build.gradle이 이 태스크의 태그를 test에서 제외하는 이유도 같다. 성능 회귀가 의심될 때 사람이 이름으로 부른다.
  • openapiCheckSnapshot — 드리프트 검사 자체는 이미 자동으로 돈다. 이 태스크가 감싸는 OpenApiDriftContractTest는 :sample-portfolio:test의 일부이고, 그건 check 안이며 stage 1에서 실행된다. 이 태스크의 고유한 역할은 -PapproveOpenApiChange로 커밋된 스냅샷을 다시 만드는 것 — 의도된 API 변경을 사람이 승인하는 지점이다. 자동으로 돌리면 승인이 승인이 아니게 된다.

더 알아보기

S
Description
No description provided
Readme
46 MiB
Languages
Java 97.6%
Python 1.1%
Shell 0.9%
Go Template 0.3%