문제: 재리뷰 수정 커밋(bbe944bd)만 다시 본 2차 재리뷰가 Important 7건,
Minor 22건을 찾았다. 결과 불명 503 뒤 같은 키를 다시 보내면 Redis
store가 lease 지난 실행을 넘겨받아 작업을 다시 돌렸다. replay TTL이
lease보다 짧으면 lease 도중 key가 사라져 같은 키가 두 번 실행됐다.
@SystemInvoked 규칙이 매뉴얼 09장의 이벤트 소비 경로까지 막았다. V22가
outbox_event에 가장 강한 잠금을 lock_timeout 없이 걸었다. prod의
fixture- 거부가 HOSTNAME 같은 비밀 아닌 값까지 막았다. 데모 허용 목록의
test·demo 프로필로 sample이 뜨지 않았다. 기동 rule bean의 @Value 필드가
조용히 null이 됐다.
방법: 영역별 4묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 9.1절이다.
- 두 멱등성 store가 같은 계약을 따른다. lease가 지난 실행 기록은 다시
돌리지 않고 포기로 표시해 500 RECOVERY_REQUIRED로 답한다. 기록 수명은
lease + replay TTL이고, replay-ttl < processing-lease면 기동이 실패한다.
- 사용자 transport만 @SystemInvoked use case에 닿지 못한다. 메시지
handler·scheduler는 새 표시 @SystemCaller(reason)를 달고 use case를
생성자에서 new로 만든다. 매뉴얼 경로를 테스트로 고정했다.
- 아직 어디에도 적용되지 않은 마이그레이션(V20·V22·알림 V11~V13·sample
V8_1·grpc V002·V003)에 lock_timeout 5s를 넣고, 텍스트 검사기와 실 PG
lane을 더했다. 이미 배포된 24개는 동결 목록으로 둔다.
- fixture- 검사는 비밀로 분류된 값만 본다. sample은 local·test·demo에서
object storage를 끈다. 기동 rule bean에 주입 멤버가 있으면 모든
프로필에서 기동이 실패한다. 리뷰어가 제안한 "static @Bean 선언 강제"는
문제없는 등록을 막고 @Value 필드는 통과시켜서 버렸다.
- 이 수정 전에 move된 파일의 쿼터 차이를 찾는 쿼리와 재계산 SQL을
docs/fileserver/operations.md에 적었다.
위험·한계: lease 뒤 늦게 끝난 첫 시도의 결과는 기록되지 않는다(그 요청도
500). @SystemCaller가 없는 메시지 handler, 주입 멤버가 있는 기동 rule,
working-directory 없이 ./gradlew를 부르는 workflow 명령은 파생 서비스에서
새로 실패하거나 세지지 않는다(업그레이드 안내 B-14~16·B-36·B-39).
spotbugsTestFixtures는 게이트 밖이고 기준 커밋에서도 실패하며, 새 검사기의
정규식 경고 8건이 더해졌다. 실제 CI runner 실행은 확인하지 못했다(Gitea
repo의 Actions가 꺼져 있다).
검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 쿼터 재계산
SQL은 실 PostgreSQL 16에서 차이 2행 → 0행을 확인했다.
Refs: docs/reviews/2026-11-03-rereview/README.md 9·9.1·10절
BREAKING CHANGE: replay-ttl < processing-lease 설정은 기동 실패, ledger
release가 claim token을 받는다, HttpBodyReadException(IOException 하위)이
본문 실패를 싣는다, 기동 rule·비밀 목록 bean의 주입 멤버 금지,
verifyStrictLaneStages가 workflow 명령의 working-directory로 빌드를 정한다.
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와 의도적으로 구분된다. 이쪽은 시작 검증(필수 어댑터/조정 빈이 꺼져 있음)이고, 후자는 비활성 옵션 어댑터에 대한 런타임 호출이다.