- 결정 16: `ca-skeleton.*`·`backend.graphql` 등 → `app.*`(APP_* env 키 이름 유지), selector 키 상수 하나(`CapabilitySelectors`), 바인딩만 되던 `streaming-idle` 삭제 - `StrictSettingsBinder`가 env 오타까지 거부 — 모든 capability(graphql·websocket·mongo는 edge 제약으로 파일만 strict), httpclient 리플렉션 `HttpClientEnvironmentKeys` 삭제 - persistence-jpa가 `APP_DATASOURCE_PASSWORD` secret 요구를 기여(bootstrap이 JPA 스위치를 읽지 않음), Redis ACL fixture에서 pub/sub 권한 제거 - 결함 수정: SMTP 설정 env 이름 충돌(P20-new-1), `bindExcept`가 system env까지 filter(P20-new-2), graphql 빈 deployment-mode 메시지(P20-new-6) - 통합: P30과 충돌 11건(P30의 명시적 bean 구조 유지), P30 코드의 옛 키를 app.*로, persistence-jpa 포맷 - 현황표: 소유자 결정 36(persistence-jpa 설정은 플랫폼 키만 app.persistence-jpa.*로, 공유 기능 트리 예외), 재개 문서에 일시 정지 상태 Wave 3 종료 검증: check · ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck · architectureCheck verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest · integrationCheck · -p build-logic test · -p optional-platforms ci · :app-bootstrap:qualificationBootJar releaseCheck 통과 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
adapter:outbound:support — 설계 결정 참조
아웃바운드 기술 어댑터(:adapter:outbound:messaging, :adapter:outbound:cache-redis,
:adapter:outbound:notification, :adapter:outbound:httpclient)가 공유하는 베이스 모듈. 패키지
루트: dev.caskeleton.adapter.outbound.support.
허용/금지 의존 정책은 src/build.gradle 의
allowedProjectDependencies['adapter:outbound:support'] 항목이 SSOT 다(이 모듈은 아직 별도
CLAUDE.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 의 genericApplication 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와 의도적으로 구분된다. 이쪽은 시작 검증(필수 어댑터/조정 빈이 꺼져 있음)이고, 후자는 비활성 옵션 어댑터에 대한 런타임 호출이다.