Files
clean-architecture-backend-…/src/adapter/outbound/support
DongHyeonka cbfa776270 build!: 시험 classpath·이미지 고정·카탈로그·API surface 입력을 정본대로 맞춘다
문제:
- ca.spring-library가 모든 spring leaf(30)의 testImplementation에
  spring-boot-starter-webmvc-test를 넣어, MockMvc를 쓰지 않는 23 leaf가 Tomcat을
  시험 classpath에 resolve하고 lock했다.
- container-images.properties 머리말은 「digest로 고정」이라는데 postgres-17·18이
  tag만이었다. 머리말은 「쓰는 lane만 다시 돈다」고 했지만 파일 전체가 모든 Test
  task의 입력이라 이미지 하나만 바꿔도 모든 lane이 다시 돈다. postgres-16-4는
  아무도 읽지 않았다.
- libs.versions.toml에 아무도 읽지 않는 칸이 있었다(라이브러리 9, 버전 4,
  루트에 적용하지 않는 플러그인 4).
- config/spotbugs/exclude.xml에 없는 클래스의 항목이 있었다(exclude-test.xml에
  이미 있다).
- notification의 API surface가 상대 경로로 application-notification 소스를
  가리켰고, ApiSurface 플러그인은 없는 추가 root를 말없이 건너뛰어 승인 update가
  줄어든 표면을 기록할 수 있었다.
- verify-mongodb-platform.sh가 고르는 클래스가 없는 :app-bootstrap:test
  --tests '*CleanArchitectureTest'를 불러 늘 실패했고, 이미지 기록이 카탈로그와
  다른 tag였다.

고친 것:
- 규약은 spring-boot-starter-test만 준다. 시험이 실제로 쓰는 것을 leaf가 직접
  선언한다. MockMvc를 쓰는 web·web-advanced·web-fileserver·web-notification·
  app-bootstrap은 webmvc-test starter, graphql은 TestRestTemplate의
  spring-boot-resttestclient, durable-operation은 WebApplicationContextRunner의
  spring-web, 시험이 JSON을 읽는 objectstorage·persistence-jpa·persistence-mongo·
  notification-platform은 jackson-databind, redis-runtime은 jackson-annotations
  (compileOnly, 본 코드와 같은 이유)다. 모든 Java source set을 한 빌드에서 컴파일해
  빠진 곳이 없음을 확인하고 lockfile을 다시 만들었다(Tomcat·webmvc 시험 자동설정이
  빠짐). graphql·persistence-mongo AGENTS의 허용·시험 목록을 같이 고쳤다.
- postgres 17·18을 desktop runner에서 받은 digest로 고정했다(17.11, 18.6). 목록을
  읽을 때 digest 없는 값을 GradleException으로 거절한다(ContainerImageCatalogTest).
  머리말을 실제 캐시 동작으로 고쳤고 postgres-16-4를 지웠다. persistence-jpa
  release registry의 PostgreSQL tag는 아무도 읽지 않아 지우고, 이미지는 카탈로그가
  정한다고 적었다.
- 카탈로그의 미사용 칸을 지우고 머리말을 지금 쓰임에 맞췄다.
- 죽은 spotbugs 항목을 지웠다.
- notification은 project(':application-notification')로 root를 잡고, 없는 추가
  root는 설정 단계에서 실패한다(ApiSurfaceConventionTest).
- mongo 스크립트는 :app-bootstrap:architectureTest를 부르고, 이미지 기록은
  카탈로그 mongo-8 값을 읽는다.
- graphql build.gradle에 앞 커밋의 document-contract lane을 함께 둔다. 저장소 루트
  (ca.repository.root)와 읽는 registry 파일은 그 lane만 받고, 시험은 그 속성으로만
  루트를 읽는다(cwd에서 거슬러 찾지 않는다).
버린 대안: 이미지마다 쓰는 lane을 선언해 입력을 나누기 — lane 수십 개에 키
목록을 다시 적어야 하고 빠뜨리면 캐시가 거짓 통과한다.

검증: 아래 PR 본문(desktop resolveAndLockAll·build-logic test·모든 source set 컴파일·
leaf check).

BREAKING CHANGE: ca.spring-library가 시험 classpath에 spring-boot-starter-webmvc-test를
넣지 않는다. MockMvc·TestRestTemplate·Jackson을 그 starter로 받던 파생 leaf는 의존을
직접 선언해야 시험이 컴파일된다. 카탈로그의 digest 없는 이미지와 없는 API surface 추가
root는 설정 단계에서 실패한다. version catalog의 미사용 칸을 지웠다. 할 일은
docs/upgrade/2026-11-round9-build.md다.

Refs: RR9-04-06, RR9-04-11, RR9-04-12, RR9-04-13, RR9-04-14, RR9-04-15, RR9-04-16
2026-11-13 06:34:32 +09:00
..

adapter:outbound:support — 설계 결정 참조

아웃바운드 기술 어댑터(:adapter:outbound:messaging, :adapter:outbound:cache-redis, :adapter:outbound:notification, :adapter:outbound:httpclient)가 공유하는 베이스 모듈. 패키지 루트: dev.caskeleton.adapter.outbound.support.

허용/금지 의존 정책은 build.gradle 의 allowedProjectDependencies['adapter:outbound:support'] 항목이 SSOT 다(이 모듈은 아직 별도 AGENTS.md 를 두지 않았다). 이 문서는 코드 주석에서 덜어낸 설계 결정의 근거를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다.

왜 별도 모듈인가

옛 adapter-outbound 모듈을 기술별(messaging/cache-redis/notification/httpclient)로 쪼개면서, 네 모듈이 공통으로 필요로 하는 조각 — correlation 조회, fail-open 의존성 로깅, 공유 @Configuration 등록 지점 — 을 이 모듈로 뽑아냈다. 네 기술 모듈 모두 implementation project(':adapter:outbound:support') 로 이 모듈에 의존한다.

FailOpenDependencyLogger — WARN, ERROR 아님

실패를 ERROR 가 아니라 WARN 으로 로깅한다: cache/messaging/notification 선택형 어댑터는 fail-open 이라 의존성 실패가 나도 use case 는 성공한 것이다 — 관측은 하되 escalate 하지 않는다. 이는 호출자에게 직접 노출되는 hard failure 를 ERROR 로 올리는 httpclient 모듈의 OutboundHttpDependencyLogger 와 명확히 구분된다. 메서드 시그니처가 본문·수신자·페이로드를 받지 않아 PII 가 로그에 닿지 않는다.

OutboundCorrelation — "unknown" 센티넬

MDC 에 correlation id 가 없으면 null 이 아니라 "unknown" 문자열을 반환해 로그 라인에 필드가 비지 않게 한다. MDC 키는 SSOT(mdc-keys.yaml)를 따른다.

OutboundSupportConfig — 공유 auto-configuration seam

FailOpenDependencyLogger 빈을 @ConditionalOnMissingBean 으로 무조건 등록하는 단일 @AutoConfiguration 이다(META-INF/spring/...AutoConfiguration.imports에 등록 — 합성 루트의 component scan 없이 이 모듈이 있으면 등록된다). 네 기술 모듈이 각자 로거 빈을 중복 등록하지 않고 이 모듈에만 의존하면 와이어링되며, 포크는 같은 타입의 빈을 직접 등록해 오버라이드할 수 있다. 이 모듈 자체는 어떤 @ConditionalOnProperty 게이팅도 갖지 않는다 — 게이팅은 각 기술 모듈이 자신의 연동 client 단위로 소유한다.

messaging — 템플릿의 integration event encoder

JsonIntegrationEventEncoder가 IntegrationEventEncoderPort의 템플릿 구현이다(소유자 결정 7: outbox append는 canonical 하나, encoder는 템플릿이 준다). IntegrationEventEncoderAutoConfiguration이 context의 모든 IntegrationEventContractContribution bean으로 닫힌 catalog를 만들고, 서비스가 자기 encoder bean을 두면 물러난다.

  • 형식: shared-contract의 envelope v1(contracts/messaging/envelope/v1.schema.json) 안에 payload record를 CanonicalJson으로 한 번 렌더링해 넣는다. 한 값에는 렌더링이 하나다: component 선언 순서, 공백 없음, RFC 8259 필수 escape만, 숫자는 plain decimal. 그래서 envelope hash가 event를 대표한다.
  • 받는 component 타입은 닫혀 있다: String, 정수형, BigDecimal, Boolean, enum, Instant, LocalDate, UUID, Optional, List, public record. double/float는 거부한다(한 값에 철자가 여럿이라서). null도 거부한다 — 없을 수 있는 값은 Optional로 선언한다.
  • 시작할 때 확인하는 것: payload 타입이 IntegrationPayload를 구현한 record인지, 선언한 component 순서가 record의 것인지, 선언한 schema hash가 classpath schema 파일 bytes의 SHA-256인지. schema를 고치고 hash를 안 고치면 기동이 실패한다.
  • 확인하지 않는 것: payload를 JSON Schema로 검증하지 않는다(NetworkNT를 production에 다시 싣지 않았다). 매 event마다 검증하려는 서비스는 자기 encoder bean을 둔다.
  • partition key는 tenant·logical destination·aggregate type·aggregate id의 domain-separated SHA-256이라 한 aggregate의 event는 한 partition으로 간다.

여기 있는 이유: use case가 append 전에 encode하므로 outbox를 쓰는 모든 조립에 있어야 한다. messaging 모듈은 발행 쪽에만 있고(sample은 messaging이 없다), persistence는 직렬화를 소유하지 않는다. support는 outbound 어댑터가 있는 모든 조립에 있다.

startup — 시작 실패 계약과 모듈 기본 설정 (app-bootstrap에서 이동)

capability 모듈이 합성 루트에 의존하지 않고 같은 방식으로 실패하고, 자기 설정을 가져오게 하려고 support.startup 패키지로 옮겼다. 로거 이름(dev.caskeleton.bootstrap.runtime.startup, dev.caskeleton.bootstrap.runtime)과 로그 필드는 그대로 둬서 운영 필터가 바뀌지 않는다. logstash encoder·Logback은 compileOnly다: 애플리케이션의 로깅 스택(app-bootstrap이 둘 다 싣는다)이 제공하고, 시작 실패를 던지는 모듈(persistence-jpa, cache-redis)은 encoder를 직접 선언한다.

  • StartupOrder — 모든 EnvironmentPostProcessor의 순서표. 모듈 기본 설정(MODULE_DEFAULTS)이 config data 바로 뒤, 그다음 Redis·DB readiness 기여, 맨 끝에 검증기들이다.
  • ReadinessGroup — readiness 그룹에 contributor를 붙이는 유일한 방법.
  • RuntimeWarnings — 경고 두 종류(meter 기록 실패, 설정 대체)의 구조화 필드.
  • ModuleDefaultsEnvironmentPostProcessor — 모듈이 config/module-defaults/<모듈>.yml에 둔 기본 설정을 가장 낮은 우선순위로 읽는다. 모듈을 고르면 설정이 따라오고 지우면 같이 사라진다. 이 모듈의 spring.factories에 등록돼 있다. 규칙: 의존성 closure(modules.json)에 support가 있는 모듈은 전부 이 로더를 쓴다(yml만 두면 되고 코드 의존은 필요 없다). support에 닿지 않는 모듈 (persistence-mongo, graphql)만 자기 activation EPP가 config/<이름>.yml을 읽는다.

시작 실패 타입(StartupErrorCode / StartupPhase / StartupFailures / *Exception)

  • StartupErrorCode — 네 가지 시작 실패 원인을 (레지스트리 error code, 표준 프로세스 exit 코드, StartupPhase)로 묶는다. exit 78(env 누락/오류)과 70(마이그레이션 실패)은 sysexits 표준 (EX_CONFIG, EX_SOFTWARE)과 정렬돼 외부적으로 방어 가능하다. 반면 exit 71(프로파일 불일치)과 72(필수 어댑터 비활성)는 ca-tmpl 내부 규약이다 — sysexits 의 EX_OSERR/EX_OSFILE이 이 의미와 맞지 않아, 외부 표준이 아니라 내부 룩업 테이블 값으로 정했다. exit 코드는 carrying 예외가 ExitCodeGenerator를 구현하기 때문에만 JVM 종료 상태가 된다.
  • StartupPhase — 실패 원인을 운영자가 로그에서 구분할 수 있게 하는 startup.phase 필드다. 시작 실패는 요청이 아직 없으므로 HTTP 에러 응답에 절대 실리지 않는다. 따라서 구조화 로그의 startup.phase가 kubectl logs/describe에서 네 가지 원인을 가려내는 유일한 계약이다. wire 이름은 dash-case(env-validation | migration | adapter-enablement | profile-check)이며, MDC 키가 아니라 Logstash structured argument 로 방출되므로 snake_case MDC 키 레지스트리 규칙은 적용되지 않는다.
  • StartupFailures — 시작 실패를 던지는 단일 출처로, 예외 생성 전에 구조화 로그를 먼저 방출한다. "throw 직전 각 validator 가 직접 logger 를 호출"하는 패턴을 중앙화해, 어떤 시작 가드도 원인/구분자 없는 실패를 던지지 못하게 한다. 로그는 startup.phase / error.code / error.category 세 필드를 Logstash structured argument 로 싣고, cause 가 있으면 error.root_cause.class / error.root_cause.message 요약 필드만 추가한다. 원본 cause 는 반환되는 StartupFailureException에 보존하지만 SLF4J throwable 인자로 넘기지 않는다. 따라서 canonical startup-failure 로그는 운영자가 분류할 수 있는 요약만 남기고 프레임워크/드라이버 stacktrace 를 출력하지 않는다.
  • StartupFailureException — 시작 실패의 유일한 타입이다. 원인은 싣고 있는 StartupErrorCode가 말하고(errorCode()), ExitCodeGenerator로 그 코드의 exit 코드를 JVM 종료 상태로 만든다. 코드마다 subclass(생성자로 코드만 넘기던 4개)를 두던 구조는 없앴다(S6-#13). 생성은 StartupFailures 팩토리만 한다 — 생성자는 package-private 이고, 팩토리가 구조화 로그를 함께 남긴다. context refresh 가 실패하면 SpringApplication의 SpringBootExceptionHandler (부팅 스레드의 uncaught-exception handler 로 설치됨)가 실패 예외에서 getExitCode()를 읽어 System.exit(code)를 호출한다 — main() 수정이 필요 없다. IllegalStateException을 상속하는 이유는 과거 StartupSafetyValidator가 IllegalStateException을 던졌기 때문으로, 타입드 예외로 업그레이드한 뒤에도 소스/동작 호환을 유지하기 위함이다.
  • StartupFailureExceptionReporter / StartupFailureSpringBootLogFilter — Spring Boot 의 중복 startup stacktrace 를 억제한다. reporter 는 failure cause chain 에 StartupFailureException이 있을 때만 true를 반환해 Boot 의 generic Application run failed 출력을 "이미 보고됨"으로 처리한다. 이후 Boot 가 반쯤 초기화된 context 를 닫다가 Unable to close ApplicationContext를 다시 남길 수 있으므로, canonical startup-failure 로그가 이미 찍힌 프로세스에서는 해당 org.springframework.boot.SpringApplication 중복 메시지만 logback turbo filter 가 차단한다. 일반 startup failure 가 아닌 예외와 다른 logger/message 는 기존 Spring Boot 로그 경로를 유지한다.
  • REQUIRED_ADAPTER_DISABLED(StartupFailures.requiredAdapterDisabled)는 런타임-라이프사이클의 ADAPTER_DISABLED와 의도적으로 구분된다. 이쪽은 시작 검증(필수 어댑터/조정 빈이 꺼져 있음)이고, 후자는 비활성 옵션 어댑터에 대한 런타임 호출이다.