Files
clean-architecture-backend-…/src/bootstrap/app

app-bootstrap — 설계 결정 참조

애플리케이션 진입점이자 합성 루트(composition root) 모듈. 패키지 루트: dev.caskeleton.bootstrap.

이 모듈은 비즈니스 로직을 담지 않는다. Spring Boot 기동, 런타임 설정 바인딩, 기본 runtime 모듈 간 최종 와이어링, 그리고 composition classpath를 대상으로 한 중앙 아키텍처 테스트만 둔다. 모든 leaf의 프로젝트 edge는 JSON registry를 읽는 Gradle 방향 게이트가 별도로 검사한다. 허용/금지 의존, 책임 범위, 테스트 명령 같은 모듈 규칙의 SSOT 는 AGENTS.md 다.

기본 composition의 SSOT는 build.gradle의 실제 project dependency graph다. registry는 runtime membership 목록을 두지 않는다. allowed_dependencies 밖의 project는 방향 게이트가 막는다.

conditionalTransportBuildContractTest는 GraphQL/gRPC/WebSocket 세 leaf를 test-only classpath에서 함께 resolve하는 qualification composition이다. 세 leaf 모두 기본 조립에는 없다.

기능 추가 = 한 줄 + env

기본 조립(bootJar)은 web, 관측, domain-core·application-core·shared-contract, support, identifier뿐이다. 나머지 capability(JPA, Redis, Kafka, Mongo, GraphQL, HTTP client, object storage, WebSocket, gRPC, 파일 서버, 알림)는 build.gradle에 주석 처리된 runtimeOnly project(...) 한 줄씩으로 있다. 주석을 풀면 그 모듈이 자기 AutoConfiguration.imports와 설정 기본값으로 켜지고, 줄을 지우면 함께 사라진다. 있는 모듈은 자기 enabled 키(기본 true)를 false로 줄 때만 꺼진다. 합성 루트는 capability 목록을 따로 들고 있지 않다(스위치 목록, scan 제외 정규식, 의존 검사기 없음). component scan은 dev.caskeleton.bootstrap만 보고, web(WebAdapterAutoConfiguration·WebSecurityAutoConfiguration·WebMethodSecurityAutoConfiguration)과 support(OutboundSupportConfig)도 자기 auto-configuration으로 들어온다.

  • 줄마다 필요한 env와 끄는 키: docs/build.md의 "기능 추가 = 한 줄 + env" 표.
  • 줄을 바꾼 뒤: ./gradlew :app-bootstrap:resolveAndLockAll --write-locks로 strict lock을 갱신한다.
  • ./gradlew :app-bootstrap:qualificationBootJar는 main runtime에 모든 capability를 더한 jar를 만든다. compose 레인과 CI용이고, 배포 artifact는 bootJar다.
  • build.gradle의 capabilityProjects 목록이 capability 전체를 한 번 적는다. 전체 저장소 ArchUnit import(architectureTest)와 qualification jar가 이 목록을 읽고, 운영 runtimeClasspath에는 고른 줄만 들어간다. 새 capability leaf는 이 목록과 주석 한 줄, 두 곳에 추가한다.

이 문서는 코드 주석에서 덜어낸 설계 결정의 근거를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 본문은 한국어로 쓰고, 클래스·Spring API·메트릭 이름처럼 꼭 필요한 기술 용어만 영어로 남긴다. 별도 추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로 풀어 둔다.

목차


runtime/startup — Fail-fast 시작 파이프라인과 시작 실패 분류

잘못 설정된 채로 기동돼 트래픽을 받는 것보다, 기동 시점에 명확한 이유와 함께 멈추는 편이 안전하다. 이 패키지는 그 "빨리·명확하게 실패시키기(fail-fast)"를 담당한다.

AuthenticationModeCompositionConfig

app.security.auth-mode의 기본값은 jwt이며 jwt|redis-session 중 정확히 하나만 허용한다. 모드는 web leaf의 SecuritySettings(app.security 전체의 유일한 소유자, strict 바인딩)에서 읽는다. 예전에는 bootstrap의 AuthenticationModeSettings가 같은 prefix를 관대하게 한 번 더 바인딩했다(리뷰 07-10). JWT mode는 jwtDecoder가 있어야 하고 Redis session repository/filter가 있으면 기동을 거부한다. Redis session mode는 반대로 jwtDecoder를 거부하고 redisVersionedSessionRepository와 springSessionRepositoryFilter가 모두 있어야 한다. 이 검증은 bean name만 확인하므로 bootstrap이 Spring Session/Redis 구현 타입을 직접 의존하지 않으며, composition 누락과 이중 활성화를 context refresh 완료 전에 실패시킨다.

관계형 기동 가드(FlywayProdSafetyValidator, RequiredEnvironmentValidator, 마이그레이션 전략 MigrationStartupRunner)는 adapter:outbound:persistence-jpa로 옮겼다. 설계 근거는 그 모듈 README의 "startup" 절에 있다.

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

  • 실패 분류와 구조화 로그 계약은 adapter:outbound:support의 support.startup 패키지로 옮겼다 (capability 모듈이 합성 루트에 의존하지 않고 같은 exit 코드로 실패하게 하려고). 설계 근거는 그 모듈 README에 있다. 합성 루트에는 StartupFailureExceptionReporter(Spring Boot 보고 억제)와 StartupFailureSpringBootLogFilter만 남는다.

runtime — 시크릿 소스 선택과 런타임 안전 가드

시크릿을 어디서 읽을지(env / Vault / 클라우드 시크릿 매니저)를 인터페이스 뒤로 숨기고, 위험한 런타임 설정값은 기동 시점에 막는다.

SecretSource

  • 시크릿 해석을 인터페이스 한 겹 뒤로 숨긴 backend seam 이다. 시크릿이 필요한 코드는 이 인터페이스에만 의존하고, 실제 백엔드(env / Vault / AWS Secrets Manager / GCP Secret Manager)는 SecretSourceFactory가 설정값으로 고른다. 설정과 구현 선택을 한 factory에 모으는 패턴이다. 백엔드를 추가하는 비용이 "새 SecretSource 구현 1개 + SecretSourceStrategy enum 값 1개 + factory case 1개"로 고정되고, 소비자(SecretSourceValidator, 향후 어댑터)는 전혀 손대지 않는다.
  • 빈 문자열은 "없음"으로 취급한다. resolve가 blank 값을 Optional.empty()로 돌려주지 않으면, "값은 존재하지만 비어 있는" 시크릿이 존재 검사(presence check)를 통과해 버려 prod 부팅을 막을 수 없게 된다.

SecretSourceStrategy

  • enum 값 하나가 곧 백엔드 하나라는 확장 규약을 못 박는다. app.secret-source.strategy로 바인딩되며 ENVIRONMENT만 기본 제공한다. 미래 백엔드(VAULT, AWS_SECRETS_MANAGER, GCP_SECRET_MANAGER)는 주석으로만 남겨 두어, 추가 절차가 "enum 값 + SecretSource 구현 + factory case"임을 코드에서 바로 읽히게 했다(rate-limit algorithm enum 패턴과 동일).

SecretSourceSettings

  • 설정이 없어도 동작하는 기본값(ENVIRONMENT)을 박았다. 스켈레톤은 별도 설정 없이 바로 부팅돼야 하므로, strategy가 null이면 ENVIRONMENT로 보정한다. 백엔드 교체는 코드 수정이 아니라 설정 한 줄로 끝난다.

SecretSourceConfig

  • 시크릿 백엔드와 그 시작 가드를 composition root 에서만 와이어링한다. SecretSourceFactory로 선택된 SecretSource(기본 ENVIRONMENT)와, 그것을 통해 필수 시크릿을 검증하는 SecretSourceValidator를 빈으로 노출한다. 검증기를 Spring 스테레오타입 없는 일반 클래스로 둔 이유는 단위 테스트 가능성을 지키기 위함이고, 이 config 가 유일한 production 와이어링이다.
  • RuntimeSafetyConfig와 일부러 분리했다. 시크릿 계약은 secrets-config-source-contract 가 소유하고, 런타임 안전 토글은 env-driven-runtime-configuration 이 소유한다. 소유 경계를 코드 구조로 보존하기 위해 한 config 로 합치지 않았다.

SecretSourceFactory

  • 유일한 확장 지점을 switch 하나로 모았다. 새 백엔드는 SecretSourceStrategy 값 + SecretSource 구현 + 이 switch의 case 추가로 끝나고 소비자는 바뀌지 않는다. factory 한곳에 "확장 비용이 어디에 있는가"를 보이게 했다.

EnvironmentSecretSource

  • 기본 백엔드는 Spring Environment에서 읽는 것이다. ENVIRONMENT 전략은 시크릿이 env var / 마운트 파일 / application.yml로 들어와 Spring 자체 property resolution 으로 바인딩됨을 전제한다. Vault·AWS·GCP 연동은 소비자를 건드리지 않고 SecretSourceFactory 뒤에 별도 SecretSource 구현으로 추가하면 된다.

SecretSourceValidator

  • prod 에서 깨지면 부팅 자체를 거부하는 fail-fast 가드다. 두 가지 prod 불변식을 context refresh 완료 전에 강제한다. (1) __LOCAL_DEV_ 접두사를 가진 dev/local 가짜 자격증명 값이 prod 프로파일에 도달하는 것은 잘못 로드된 사고이므로 부팅을 중단시킨다. 비밀값이 fixture-로 시작해도 같다. 이 저장소가 lane용으로 적어 둔 공개 비밀번호(compose/redis/acl의 Redis ACL fixture, compose lane의 REDIS_LANE_*)라서, lane 환경이나 lane ACL 파일을 베낀 배포가 그대로 운영에 뜨는 것을 막는다 (review 2026-11-03 RR-07-04). 이 검사는 비밀값만 본다 — 레지스트리의 secret 행 (CLASSIFIED_SECRETS), 모듈이 기여한 비밀, 환경 값에 든 secret://…/<VAR> 참조가 가리키는 변수 (review 2026-11-04 RR2-04-01). 코드에 든 참조(Redis SDK admin 계정의 RedisAccountContribution)는 보지 못하므로, 그 계정을 조립하는 쪽이 변수를 RequiredProductionSecrets bean으로도 낸다(RR3-04-03, src/adapter/outbound/redis-sdk/README.md). fixture-는 평범한 단어라서 fixture-api Deployment의 pod 이름 (HOSTNAME)이나 앱 이름까지 거부하면 운영에서만 기동이 막혔다. __LOCAL_DEV_ 표시는 정당한 값이 가질 일이 없으니 모든 값을 본다. 실패 메시지는 변수 이름만 적고 값은 적지 않는다. (2) 레지스트리에서 secret + prod_default: null로 분류된 모든 키는 prod 에서 비어 있지 않게 주입돼야 한다 — 빈 시크릿으로 부팅하는 것은 금지다. dev/local 프로파일은 두 검사를 건너뛴다(__LOCAL_DEV_*가 의도된 로컬 폴백이므로).
  • 다른 싱글톤을 만들기 전에 판정한다(StartupRule, 07-02). 예전에는 SmartInitializingSingleton 이라 모든 싱글톤 생성 후에 돌았다. 그래서 비밀값이 빠진 prod 배포도 DataSource가 연결을 열고 Flyway가 마이그레이션한 뒤에야 거부됐다. 지금은 support의 StartupRuleRunner가 bean factory post-processor 단계에서 부른다. 이를 위해 SecretSourcePort bean을 받지 않고 같은 선택 규칙 (SecretSourceFactory.fromEnvironment)으로 백엔드를 직접 만든다. 모듈 기여(RequiredProductionSecrets)는 규칙이 돌 때 읽으므로, 기여하는 bean은 static @Bean으로 선언한다(설정 클래스를 일찍 만들지 않게).
  • 필수 시크릿 검사는 Spring 환경이 아니라 SecretSource 백엔드를 통해 한다. 존재 검사를 백엔드(secretSource.resolve(key)) 경유로 하기 때문에, env → Vault/AWS 백엔드 교체 시에도 검사가 자동으로 따라간다. 검사를 Spring Environment에 고정했다면 백엔드를 바꿀 때 검증 로직이 함께 끊겼을 것이다.
  • REQUIRED_PROD_SECRETS는 레지스트리와 1:1로 강제된다. 이 in-code 상수는 docs/registries/secrets-classification.yaml의 secret 행과 정확히 일치해야 하며, SecretsClassificationRegistryTest가 1:1 일치를 단언한다. 그래서 레지스트리에 시크릿을 추가/제거하고 이 상수를 갱신하지 않으면 빌드가 깨진다 — drift 를 컴파일·테스트 단계에서 잡는다.
  • capability의 시크릿은 그 모듈이 기여한다. 선택한 역할에만 필요한 시크릿(Redis 역할별 비밀번호·HMAC 등)은 이 상수에 없다. 소유 모듈이 RequiredProductionSecrets 빈으로 "지금 선택된 역할이 요구하는 시크릿"을 알려 주고(Redis는 cache-redis의 RedisProductionSecrets), 이 가드는 그 이름들이 백엔드에서 풀리는지만 본다. 레지스트리에서는 그 행들이 required_when을 가진다. 관계형 DB 비밀번호(APP_DATASOURCE_PASSWORD)도 같다: persistence-jpa가 켜져 있는 동안 JpaStartupAutoConfiguration이 기여하고, 이 가드는 그 모듈의 스위치를 읽지 않는다(P22-new-1).
  • prod 판정은 대소문자 무시다. SPRING_PROFILES_ACTIVE=PROD 같은 배포 오타도 prod 가드를 발동시켜야 하므로 equalsIgnoreCase로 비교한다(Environment#matchesProfiles는 대소문자를 구분해 "PROD"를 통과시킨다).

환경만 읽는 검사(RuntimeNumericBoundsValidator, ErrorDetailExposureSafetyValidator와 persistence-jpa의 datasource·Flyway·OSIV·TLS·vendor·Hikari 검사)는 StartupRule이다: 위반 목록만 돌려주고, adapter:outbound:support의 StartupRuleRunner 하나가 다른 싱글톤을 만들기 전에(bean factory post-processor 단계) 규칙마다 그 phase의 종료 코드로 실패시킨다. 그래서 prod 금지 값은 DataSource가 연결을 열거나 Flyway가 마이그레이션하기 전에 거부된다. 규칙은 그만큼 일찍 만들어지므로 static @Bean 메서드로 선언한다. 같은 단계에서 도는 것은 이제 셋이 더 있다. SecretSourceValidator(모듈이 기여한 비밀값 이름을 규칙이 돌 때 읽는다), StartupSafetyValidator(bean 정의만 보고 bean은 만들지 않는다), LoggingConfigurationRule(Logback이 쓸 수 없는 app.logging.* 값). DB 연결이 꼭 필요한 persistence-jpa의 datasource 버전 검사는 bean으로 남되, 모든 Flyway initializer가 그 검사에 dependsOn 하도록 묶어 마이그레이션보다 먼저 돈다. 부팅 전에 돌아야 하는 profile 규칙 (RuntimeEnvironmentProfileValidator)은 EnvironmentPostProcessor로 남는다.

관계형 설정 가드(HikariPoolConstraintValidator, OpenInViewSafetyValidator, JpaDangerousConfigurationGuard, PostgreSqlTransportSecurityValidator, PersistenceVendorProdSafetyValidator)는 adapter:outbound:persistence-jpa로 옮겼다. 풀 크기 하한(APP_DATASOURCE_POOL_MAX_SIZE >= 1, APP_DATASOURCE_POOL_MIN_IDLE >= 0)도 이제 그쪽 HikariPoolConstraintValidator가 검사한다.

RuntimeNumericBoundsValidator

  • 고위험 숫자 노브(pool/thread 사이징)만 일부러 좁게 검증한다. pool/connector 사이징 키는 Spring-native property(spring.datasource.hikari.*, server.tomcat.*)로 직결되고 env-keys.yaml이 각각을 positive_int / non_negative_int로 표시하지만, 이 표시는 그동안 강제되지 않았다 — Hikari/Tomcat 이 결국 거부하더라도 난해한 메시지로 init 시점에야 거부했다. 이 검증기는 resolved Spring property 를 읽어, 운영자가 실제 설정한 APP_* 키를 담은 메시지로 일찍 부팅을 실패시킨다. 잘못 설정하면 실제 런타임 장애로 이어지는 키(pool/thread 사이징)에만 범위를 한정했고, Logback 소유 로그 사이징·Spring Duration 키는 (해당 라이브러리가 검증하므로) 범위 밖이다.
  • 읽기 전용으로 Spring 바인딩을 중복하지 않고, 부재 키는 skip 한다. 값이 없으면 placeholder/ 프레임워크 기본값이 소유하므로 건너뛰고, 범위를 벗어난 있는 값만 거부한다("lenient default 금지").

StartupSafetyValidator

  • bean 정의가 다 모인 뒤, 싱글톤을 만들기 전에 판정한다(StartupRule, 07-02). EnvironmentPostProcessor는 bean 정의가 생기기 전이라 bean 존재 여부를 볼 수 없다. 예전의 SmartInitializingSingleton은 모든 싱글톤 생성 후라, lock 없는 multi-instance 배포가 저장소에 연결하고 마이그레이션한 뒤에야 거부됐다. bean factory post-processor 단계는 둘 사이다: 이름·타입 검사(containsBean, isTypeMatch)는 정의만으로 답하므로 아무 bean도 만들지 않는다.
  • prod 에러 상세 노출은 ErrorDetailExposureSafetyValidator가 막는다(이 클래스가 아니다). prod에서 spring.web.error.include-stacktrace·include-message·include-binding-errors가 never가 아니거나 include-exception=true면 PROFILE_MISMATCH(exit 71)로 부팅을 중단한다. env override로 들어온 값도 같다. 요청 본문 캡처는 RequestLoggingFilter가 body를 읽지 않는 계약으로 막는다.
  • multi-instance 가 켜지면 실제 cross-instance lock provider가 조립되어 있어야 한다. APP_MULTI_INSTANCE_ENABLED=true일 때 distributedLockProvider가 없거나 DistributedLockPort 타입이 아니면 REQUIRED_ADAPTER_DISABLED(exit 72)로 실패시킨다. cache refresh coordination은 optional efficiency이고, rate-limit/outbox는 각 capability가 켜졌을 때 자기 provider 계약으로 검증하므로 이 전역 스위치가 사용하지 않는 capability까지 강제로 요구하지 않는다.
  • prod 판정은 대소문자 무시다. SPRING_PROFILES_ACTIVE=PROD 오타도 prod-safety 가드를 발동시켜야 하므로 equalsIgnoreCase로 비교한다.

concurrency — 도메인 컨텍스트 전파 (composition:service-runtime으로 이동)

DomainContextConfig는 composition:service-runtime으로 옮겼다. 근거는 그 모듈의 README.

async — 비동기 executor 컨텍스트 전파와 포화 처리

AsyncContextTaskDecorator

  • executor 경계를 넘을 때 caller 스레드의 컨텍스트를 worker 스레드로 옮기는 단 하나의 TaskDecorator다. MDC 는 submit 시점에 맵 전체를 복사한다(MDC.getCopyOfContextMap()). 그래서 async 전파 대상 4개 foundation 키(request_id/trace_id/correlation_id/tenant_id)와 span_id(SLF4J-Micrometer tracing bridge 가 MDC 에 써넣는 값)가 worker 로그 라인에 그대로 따라온다. 특정 상수 holder(MdcKeys)에 결합하지 않고 맵을 통째로 복사하는 이유는, 그래야 그 시점에 존재하는 모든 키를 빠짐없이 옮길 수 있기 때문이다.
  • domain 컨텍스트는 직접 복사하지 않고 shared seam(DomainContextPropagator.wrap)에 위임한다. 이 브랜치는 executor 배선만 소유하고, caller→worker 의 실제 hand-off 는 seam 이 소유한다는 책임 분리에 따른 것이다.
  • trace/span "문자열"만 옮기지 Micrometer Observation scope 는 worker 스레드에서 다시 열지 않는다. 그래서 로그 연속성은 유지되지만, worker 에서 새로 만든 child observation 은 caller 의 span 아래로 nesting 되지 않는다. 완전한 scope 전파는 io.micrometer:context-propagation + Spring 의 ContextPropagatingTaskDecorator가 필요한데, 그 라이브러리를 의도적으로 classpath 에 두지 않았다. 따라서 "수동 4-key copy decorator" 경로를 채택하고, worker 스레드 span 이 정말 필요한 프로젝트를 위해 라이브러리 업그레이드를 확장 지점(seam)으로 문서화해 둔다.
  • SecurityContext principal 은 일부러 전파하지 않는다. user_principal은 전파 대상이 아니고, pooled 로 재사용되는 worker 스레드에 SecurityContext를 복사하는 것은 stale-context 위험이기 때문이다. principal 이 worker 에서 진짜 필요한 use case 는 자기 executor 를 Spring Security 의 DelegatingSecurityContextTaskExecutor로 감싸서 명시적으로 opt-in 한다.
  • decorator 는 대칭적이다. 태스크 실행 후 worker 스레드의 이전 MDC 를 복원하므로, pooled 스레드가 한 태스크의 컨텍스트를 다음 태스크로 흘리지 않는다.

AsyncExecutorConfig

  • Spring Boot 가 auto-config 하는 applicationTaskExecutor를 bounded pool 로 교체한다. Boot 기본 executor 의 큐는 unbounded(Integer.MAX_VALUE)라 금지된다. 빈 이름을 applicationTaskExecutor로 두는 이유는 Boot 의 @ConditionalOnMissingBean(Executor.class) auto-config 를 back-off 시키면서, 동시에 @Async가 resolve 하는 바로 그 executor 가 되게 하기 위함이다.
  • TaskDecorator 미설정 executor 등록은 ApplicationContext 기동 실패로 만든다. AsyncContextTaskDecorator를 executor 빈의 필수 생성자 의존으로 두었기 때문에, decorator 없이 executor 를 등록하려 하면 컨텍스트가 뜨지 않는다.
  • awaitTerminationSeconds(19)는 컨테이너 app-shutdown 예산 20s 에서 cleanup margin 1s 를 뺀 값이다. 25s 는 금지된다 — 컨테이너가 강제 종료하기 전에 graceful drain 이 끝나야 하기 때문이다.
  • executor.saturation gauge 는 살아있는 큐 깊이를 읽는다. 큐 > 용량 80% 면 p2, rejection 발생이면 p1 알림 기준이다.

AsyncExecutorSettings

  • 큐는 반드시 bounded 여야 한다. unbounded 큐는 maxPoolSize를 도달 불가능하게 만든다 — JDK ThreadPoolExecutor는 큐가 가득 찼을 때만 core 이상으로 스레드를 늘리기 때문이다. 게다가 Spring ThreadPoolTaskExecutor의 큐 기본값은 Integer.MAX_VALUE, 즉 사실상 unbounded 다. 그래서 compact 생성자가 큐 용량으로 Integer.MAX_VALUE를 거부한다 — 그만큼 큰 용량은 이름만 다른 unbounded sentinel 이기 때문이다.
  • 검증은 fail-fast(ApplicationContext 기동 실패)다. 잘못 설정된 pool 은 런타임 fault 가 아니라 deploy-time 버그이므로, 런타임까지 끌고 가지 않고 기동 시점에 즉시 터뜨린다.
  • cross-field 불변식: maxSize는 coreSize보다 작을 수 없다. core 보다 작은 max 는 무의미하고, pool 이 설정된 core 크기에조차 도달하지 못하게 만들기 때문이다.

BackgroundJobMetrics

  • 이 브랜치가 소유하는 background-job/async-executor 메트릭 어휘 SSOT 다. 메트릭 이름·태그는 docs/registries/metrics.yaml과 verbatim 일치한다: executor.saturation(gauge, executor_name), executor.rejected.total(counter, executor_name+policy), job.retry.total(counter, job_name+outcome), job.dlq.total(counter, job_name).
  • executor.* 두 meter 는 AsyncExecutorConfig가 라이브로 배선하고, job.* 두 recorder 는 어휘 표면만 먼저 출시한다. retry/DLQ 어휘는 outbox/outbound 브랜치가 나중에 retry carrier 를 고르면 소비하라고 이 브랜치가 소유한다. carrier 자체는 아직 정해지지 않았으므로, retry 엔진이 아니라 vocabulary surface 만 출시하는 것이다.
  • MeterRegistry 빈이 없으면(=classpath 에 Actuator 없음) 모든 연산이 no-op 다. ObjectProvider로 registry 를 resolve 하며, 이는 OutboxMetrics 선례를 그대로 따른다.
  • RetryOutcome enum 은 retry 어휘를 type-safe 하게 표기한 것이다. job.retry.total의 outcome 태그 값은 metrics.yaml 에서 4개(SUCCESS/RETRY/EXHAUSTED/DLQ)로 bounded 되어 있고, 미래의 retry carrier 가 이 값을 emit 한다.

LoggingAbortPolicy

  • 기본 포화 정책은 AbortPolicy다. bounded 큐가 가득 차고 pool 이 maxPoolSize에 도달하면 태스크를 거부하고 그 거부를 caller 에게 전달한다. 이 wrapper 는 bare ThreadPoolExecutor.AbortPolicy가 빠뜨리는 두 가지 계약 의무를, abort 를 다시 던지기 전에 추가한다: (1) error.code=JOB_EXECUTOR_REJECTED + category + executor_name + policy를 담은 structured ERROR 로그, (2) executor.rejected.total{executor_name, policy} counter 증가.
  • 그 다음 RejectedExecutionException을 던져 AbortPolicy 의미를 유지한다. fire-and-forget @Async caller 의 거부가 조용히 삼켜지지 않도록 하기 위함이다 — 이 예외가 async-exception 계약이 흡수하는 신호다.
  • 허용되는 유일한 대안은 CallerRunsPolicy뿐이고, 그것도 명시적 use-case 선언이 있을 때만이다. caller-runs 의 back-pressure 는 request 스레드 latency 를 갉아먹기 때문이다. unbounded 큐는 아예 금지다.

idempotency — 멱등성 executor 조립 (composition:idempotency로 이동)

executor 조립(IdempotencyAutoConfiguration)과 수명 정책(IdempotencySettings, strict 바인딩), 설정 기본값(config/module-defaults/idempotency.yml, 예전 config/capabilities.yml)은 composition:idempotency로 옮겼다(소유자 결정 3). 이 leaf는 runtimeOnly 한 줄로 받는다. 근거는 그 모듈의 README.

outbox — 트랜잭셔널 아웃박스 릴레이 (composition:outbox-relay로 이동)

relay 조립(OutboxRelayAutoConfiguration, 스케줄러·metrics·leader token·OutboxSettings)은 composition:outbox-relay로 옮겼다(소유자 결정 3 — persistence-jpa가 아닌 이유는 ArchUnit PERSISTENCE_DOES_NOT_DEPEND_ON_APPLICATION_SERVICES). 이 leaf는 runtimeOnly 한 줄로 받는다. 근거는 그 모듈의 README.

logging — 로그 시크릿 마스킹·샘플링·가명화

LogMaskingPatterns

  • 마스킹 정규식 규칙을 한 곳에만 둔 단일 진실 원천(SSOT)이다. JSON 인코더 경로 (SecretMaskingJsonGeneratorDecorator, staging/prod/default 프로파일)와 사람이 읽기 쉬운 패턴 경로 (SecretMaskingMessageConverter, local/dev)가 같은 규칙을 공유한다. 규칙을 한 군데로 모아둔 이유는, 프로파일이나 로그 포맷을 바꿔도 가려지는 시크릿의 범위가 절대 달라지지 않게 하기 위해서다. 즉 "가독성을 위해 포맷을 바꿨더니 시크릿이 다시 노출되는" 사고를 구조적으로 막는다.
  • 시크릿 값만 가리고 키/스킴은 남긴다. token=abc123 → token=****, Authorization: Bearer eyJ... → Authorization: Bearer ****처럼 동작한다. 키와 인증 스킴(Bearer 등)을 남기는 이유는 진단할 때 "어떤 종류의 자격증명이 있었는지"는 알아야 하기 때문이다.
  • 정규식 마스킹은 보증이 아니라 심층 방어(defence-in-depth)의 보조 수단이다. 1차 방어선은 "로거가 애초에 본문/페이로드를 받지 않도록 설계한 것"(FailOpenDependencyLogger)이고, 이 정규식은 그걸 빠져나간 누출을 잡는 그물이다. 키 접두어 없는 Base64URL 블롭 같은 난독화된 형태는 놓칠 수 있으므로, 새로운 누출 형태가 보이면 이 규칙 목록을 운영 중에 계속 보강해야 한다.

MetricsAsyncAppender

  • 백프레셔로 로그가 버려질 때 그 사실을 메트릭으로 노출한다. Logback AsyncAppender는 큐 여유가 discardingThreshold 아래로 떨어지면 INFO/DEBUG 같은 낮은 심각도 이벤트를 조용히 버린다 (WARN/ERROR는 항상 보존). 이렇게 조용히 사라지는 드롭은 관측이 안 되면 장애 분석 때 "로그가 비어 있는데 왜 비었는지 모르는" 상황을 만들기 때문에, 버릴 때마다 log.appender.dropped.total Micrometer 카운터를 올리고(appender·level 태그) 그다음 상위 클래스에 실제 드롭을 위임한다.
  • 카운터를 Metrics.globalRegistry로 발행한다. Logback 은 Spring 컨텍스트보다 먼저 초기화되는데, Spring Boot 가 시작 시 애플리케이션 MeterRegistry를 이 전역 컴포지트에 합류시킨다. 그래서 초기화 순서가 어긋나도 결국 평소 메트릭 엔드포인트에서 이 수치가 보인다.
  • level 태그를 INFO/DEBUG로만 한정한다. metrics.yaml의 allowed_values 계약 때문이다. 루트 레벨을 TRACE 로 낮춰야만 가능한 TRACE 드롭은 상위 클래스가 여전히 버리지만 카운트하지는 않아서, 태그 카디널리티가 레지스트리 계약을 벗어나지 않게 유지한다.

SamplingTurboFilter

  • 레벨을 의식하는 로그 샘플러다. WARN/ERROR는 절대 샘플링하지 않고 항상 통과시킨다 (FilterReply.NEUTRAL). 진단·장애 신호인 경고/오류는 100% 보장해야 하고, 샘플링 대상은 INFO 이하만이라는 정책 때문이다. INFO 이하는 확률 rate로 보존하고 나머지는 FilterReply.DENY로 버린다.
  • 단일 rate 노브로 제어한다. APP_LOG_SAMPLING_RATE(logback springProperty)에서 주입되고, 운영자가 런타임별로 설정한다(prod 0.1 = INFO 10% 샘플링, dev/local 1.0 = 전부 보존). 고트래픽 vs 일반 엔드포인트의 더 세밀한 분기는 이 전역 rate 위에 마커 기반 확장으로 문서화만 되어 있고 여기서는 구현하지 않았다.
  • 검증은 "경고 후 기본값(warn-and-default)" 방식이다. rate가 [0.0, 1.0] 범위를 벗어나면 Logback 상태 시스템에 경고를 남기고 1.0(전부 보존)으로 폴백한다. 잘못된 설정이 로그를 소리 없이 버리는 쪽으로 가지 않고, 항상 안전한 "샘플링 안 함"으로 degrade 되게 한 선택이다.

SecretMaskingJsonGeneratorDecorator

  • 시크릿 마스킹의 JSON 인코더 쪽 팔이다. LogMaskingPatterns 목록을 미리 적재한 MaskingJsonGeneratorDecorator로, staging/prod/default 프로파일의 LogstashEncoder에 연결된다. JSON 생성 시점에 마스킹하기 때문에 어떤 구조화 필드가 시크릿을 담았든 상관없이 message·MDC 값·스택 트레이스 텍스트 등 모든 문자열 값을 덮는다. 이 "어디서 새든 잡는 그물(catch-net)" 성질이 Redaction Layer 1에 요구되는 핵심이다.

SecretMaskingMessageConverter

  • 시크릿 마스킹의 사람이 읽는 PatternLayout 쪽 팔이다. local/dev 콘솔 패턴의 %maskedMsg 변환 워드로 등록되어, 가독성 위주의 인코더도 운영 JSON 경로와 똑같은 마스킹을 적용한다. 사람이 읽기 좋은 포맷으로 바꿨다는 이유로 시크릿이 다시 노출되지 않게 하려는 것이다. 여기서는 개발자 콘솔의 현실적 누출 벡터인 message 본문만 가린다(JSON 경로는 추가로 MDC·스택 트레이스 값까지 마스킹).

metrics·management/security·tracing (composition:service-runtime으로 이동)

메트릭 계약 filter(MetricsContractConfig), actuator 보안 chain(ManagementSecurityConfig), tracing 배선(TracingConfig 외 5개), 가명화(PseudonymizationConfig·PrivacySettings)는 composition:service-runtime으로 옮겼다. 근거는 그 모듈의 README.

settings — @ConfigurationProperties 검증 정책

이 모듈의 설정 record(BootstrapSettings, RuntimeSafetySettings, AsyncExecutorSettings, SecretSourceSettings)는 모듈들과 같이 StrictSettingsBinder로 묶는다: prefix 아래 모르는 키는 기본값으로 조용히 넘어가지 않고 기동을 실패시킨다(07-10). 그래서 @ConfigurationPropertiesScan은 쓰지 않는다. 설정 record 들은 대체로 두 가지 검증 전략 중 하나를 고른다: fail-fast(잘못되면 기동 중단)와 warn-and-default(경고만 남기고 안전한 기본값으로 진행). 어느 쪽을 쓰는지가 각 record 의 핵심 결정이다.

BootstrapSettings

  • appName은 비어 있으면 시작을 실패시킨다(fail-fast). app.bootstrap.* 바인딩이며, 앱 이름은 운영자가 직접 제공해야 하고 합리적인 기본값이 존재하지 않으므로, 비어 있거나 blank 면 compact constructor가 ENV_VALIDATION으로 막는다. 다른 settings 의 "warn-and-default"와 달리 여기서 fail-fast 를 택한 이유는, 잘못된 앱 이름으로 조용히 기동되는 것보다 즉시 멈추는 편이 안전하기 때문이다.

로깅 설정 (app.logging.*)

  • 읽는 곳은 logback-spring.xml 하나다. <springProperty source="app.logging.…">로 Spring Environment를 읽으므로 env(APP_LOG_*, config/observability.yml이 매핑), profile 파일, 명령행 인자가 모두 같은 길로 들어간다. 예전에는 env 이름을 직접 읽어 app.logging.*를 yml로 바꿔도 반영되지 않았고, LoggingSettings가 같은 키를 따로 바인딩해 Logback이 쓰지 않는 대체값을 경고했다(07-06). 그 record는 지웠다.
  • Logback이 쓸 수 없는 값은 기동을 멈춘다. LoggingConfigurationRule(StartupRule)이 파일 경로 공백, 보관 일수·큐 크기 하한, 시간대, 샘플링 비율 범위를 env 키 이름으로 보고한다. size 문자열은 Logback이 파싱한다.
  • 한계: Logback은 .env가 환경에 들어오기 전에 초기화된다(dotenv run listener가 Boot의 이벤트 발행보다 늦다). .env에만 있는 로깅 값은 반영되지 않으므로 export하거나 프로세스에 넘긴다. 예전 방식도 같았다.

RuntimeSafetySettings

  • 시작 시 StartupSafetyValidator가 강제하는 운영 안전 설정이다. 현재 구현된 runtime contract는 APP_MULTI_INSTANCE_ENABLED이며, 활성화 시 cross-instance DistributedLockPort가 실제로 조립됐는지 검증한다.
  • 내부 error detail 노출은 이 설정의 토글이 아니다. prod에서 spring.web.error.include-*가 켜지면 ErrorDetailExposureSafetyValidator가 기동을 막는다. body 로그 안전성은 RequestLoggingFilter가 body를 읽지 않는 계약으로 검증한다.
  • multiInstanceEnabled가 true면 shipped cross-instance DistributedLockPort가 실제로 조립됐는지 단언하고, 없거나 이름만 맞춘 잘못된 타입이면 시작을 실패시킨다. 이 스위치는 JPA-backed distributed lock 선택자다. cache refresh coordination은 optional efficiency이고, rate-limit/outbox는 각 capability의 활성화 계약이 자기 분산 보장을 검증하므로 여기서 사용하지 않는 기능까지 강제로 요구하지 않는다.

build.gradle — 의존성 구성 근거

app-bootstrap 은 합성 루트라 "왜 이 의존성이, 왜 이 scope 로" 결정이 많다. 빌드 파일에는 한 줄 요약만 두고, 비자명한 근거는 여기에 모은다. 바탕 원칙은 api vs implementation 정책(AGENTS.md): 모듈 간 의존은 기본 implementation이라 transitive 로 새지 않는다 — 그래서 테스트에서 그 타입이 필요하면 여기서 명시적으로 다시 선언한다.

런타임(production) 의존성

  • capability는 main 의존이 아니다. 알림(composition:notification-platform)을 포함한 모든 capability가 주석 처리된 runtimeOnly 한 줄이다(위 "기능 추가 = 한 줄 + env").
  • persistence-jpa는 main 의존이 아니다. 기본 조립은 관계형 저장소를 싣지 않는다 (// runtimeOnly project(':adapter:outbound:persistence-jpa') 한 줄을 풀면 켜진다). Flyway 마이그레이션 전략과 관계형 기동 가드는 그 모듈이 가져온다. 테스트는 JPA rule pack과 계약 테스트 때문에 모듈을 testImplementation으로 보지만, systemTest는 bootJar와 같은 런타임 그래프 (main runtime + 테스트 프레임워크)로 돌도록 test 의존을 물려받지 않는다.
  • spring-boot-starter-security를 compile classpath 에 두는 이유. adapter-web 이 security 를 implementation(not api)으로 선언해서 Spring Security 타입이 app-bootstrap 컴파일 경로로 새지 않는다. 그런데 ManagementSecurityConfig가 HttpSecurity/SecurityFilterChain/EndpointRequest를 쓴다. cross-cutting 보안 와이어링은 합성 루트가 소유한다는 원칙(AGENTS.md)에 따라 여기서 직접 의존한다.
  • micrometer-core — OutboxMetrics·BackgroundJobMetrics 카운터/게이지용. ObjectProvider<MeterRegistry>라 registry 가 없으면 no-op 이다(registry 는 Actuator 가 제공).
  • tracing(micrometer-tracing-bridge-otel + opentelemetry-exporter-otlp) — OTel/Micrometer tracer 런타임. exporter 는 OTEL_EXPORTER_OTLP_ENDPOINT가 비면 켜진 채로 대기만 하고 export 는 안 한다. 버전은 Spring Boot BOM 이 관리.
  • logstash-logback-encoder를 runtimeOnly가 아니라 implementation으로 올린 이유. 보통 JSON 로그 인코더는 런타임에만 있으면 되지만, StartupFailures가 StructuredArguments를 compile time에 호출해 startup.phase/error.code/error.category JSON 필드를 방출하므로 compile classpath 에 있어야 한다.
  • 기본 jar에 Jackson 2와 3이 함께 실린다 — 의도한 것이다(09-11). 애플리케이션 JSON은 Boot 4의 Jackson 3이다. Jackson 2(jackson-databind·jackson-core·jackson-dataformat-yaml· jackson-datatype-jsr310 2.21.x)는 두 의존성이 요구한다: logstash-logback-encoder 8.0(JSON 로그)과 web 어댑터의 springdoc → swagger-core-jakarta(OpenAPI 문서). 둘 다 Jackson 3 판이 없어 뺄 수 없다 (./gradlew :app-bootstrap:dependencyInsight --configuration productionRuntimeClasspath --dependency com.fasterxml.jackson.core:jackson-databind로 확인). 그래서 보안 패치는 두 계열을 따로 본다.
  • OTLP exporter는 JDK HttpClient sender를 쓴다(09-11). 기본 sender(opentelemetry-exporter-sender-okhttp)는 okhttp·okio·kotlin-stdlib(약 3 MB)를 모든 이미지에 실었다. composition:service-runtime이 그 sender를 빼고 opentelemetry-exporter-sender-jdk를 싣는다. export 동작은 TracingExportSystemTest가 확인한다.

테스트 의존성 (transitive 로 안 새서 명시 선언)

  • testImplementation project(':adapter-persistence-postgresql') — vendor 클래스 (PostgreSqlSqlStateErrorMapping/PostgreSqlOutboxClaimRepository)를 test compile 경로에 올려, full-matrix contract 테스트가 실제 production composition 을 배선하게 한다(런타임 의존은 runtimeOnly).
  • testRuntimeOnly postgresql — PG JDBC 드라이버. vendor 모듈이 runtimeOnly로 선언해 app-bootstrap 테스트 경로로 안 새므로 여기서 명시한다.
  • spring-boot-starter-data-jpa + HikariCP — adapter-persistence-rdbms 가 implementation이라 JPA/Hikari 가 compile 경로로 오지 않는다. outbox contract 테스트가 minimal Spring context 를 직접 만들어 이들이 컴파일 시점에 필요하다.
  • spring-integration-jdbc — JdbcLockRegistry/DefaultLockRepository도 rdbms 의 implementation이라 안 샌다. PostgreSqlDistributedLockIntegrationTest가 persistence-jpa Testcontainers PG DataSource 에 대해 독립 registry 두 개(= 두 인스턴스 시뮬레이션)를 직접 만들어 상호배제·리스 만료를 검증한다. 테스트 전용 — production 와이어링은 전부 DistributedLockPersistenceConfig(rdbms) 소유.
  • spring-boot-starter-json — JacksonAutoConfiguration은 jackson-databind 가 test 경로에 있어야 활성화되고, deserialization-policy 경계 테스트가 DeserializationFeature enum 을 직접 읽는다.
  • Testcontainers(postgresql/junit-jupiter) — outbox contract 테스트용. 버전은 Spring Boot BOM 이 관리.
  • spring-security-test — @WithMockUser로 actuator 보안 인가(permit-all 프로브 / 인증 필요한 링크 / 노출 안 한 loggers)를 검증한다.
  • snakeyaml — docs/registries/*.yaml 같은 checked-in YAML 레지스트리를 contract 테스트가 읽는다. adapter/outbound/messaging/release/*.yaml 카드 검증(MessagingCapabilityRegistryContractTest)은 소유자 결정 29로 adapter:outbound:messaging 테스트로 옮겼다.

Messaging qualification scaffold

adapter/outbound/messaging/release/는 first polling-producer tuple의 machine-readable 계획 truth만 보관한다. 현재 card 11개는 모두 maturity: not-implemented, evidenceFingerprint: ""이고 consumer, CDC, EOS, schema-registry 확장 row는 없다. verifyMessagingContracts는 application-core· shared-contract의 exact qualification test를 실행하고 contracts-schema/manifest.json을 쓴 뒤 그 바이트를 Draft 2020-12 common schema로 검증한다(verifyMessagingJsonSchemaV1은 R1 encoder와 함께 2026-09-25에 삭제). 나머지 verifyMessaging* 이름은 등록되지 않은 계획이다. 파일 존재, SKIP, 오래된 evidence, 다른 source digest 또는 다른 profile hash를 PASS로 취급하지 않는다. 이 scaffold는 broker client, scheduler, thread, network 또는 다른 런타임 resource를 생성하지 않는다.

ArchUnit "violation-as-data" fixture 의존성 (test 컴파일러 전용)

ArchUnit 규칙이 금지하는 타입을 fixture 가 일부러 import 해서, 규칙이 실제로 그 위반을 잡는지 증명한다. production classpath 엔 없어야 하므로 전부 testCompileOnly이고, 각 금지 glob 을 독립적으로 증명하려고 의존성을 쪼개 둔다.

  • spring-tx — ..architecture.violations.*의 일반 위반 fixture.
  • spring-webmvc / spring-websocket / jakarta.websocket-api — streaming 위반 fixture + over-block 가드(streaming-response-contract). spring-web(org.springframework.http..)는 spring-webmvc 를 통해 transitive 로 도착한다.
  • kafka-clients / jakarta.ws.rs-api — transport-free 도메인 이벤트 fixture (domain-modeling-guardrails)가 금지된 broker/wire/HTTP 패키지를 import 한다.
  • graphql-java (architectureTestCompileOnly) — SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS의 사용자 전송 타입 목록 중 graphql.. 항목을 증명하는 fixture(GraphQlJavaSystemCallerFixture)가 graphql-java 타입 하나만 쓴다. runtime 은 GraphQL adapter 가 이미 같은 버전을 싣는다(lock 동일).
  • spring-messaging (architectureTestCompileOnly) — 사용자 전송 타입 목록의 STOMP channel interceptor 항목(ChannelInterceptor·ExecutorChannelInterceptor)을 증명하는 위반 fixture (violations/configuration/stomp/)와 허용 fixture(inbound channel 설정만 하는 SystemCallerBesideStompBrokerSetupFixture, 따로 둔 interceptor 설정 FrameInterceptorConfigurationFixture)가 쓴다. runtime 은 WebSocket adapter 가 이미 같은 버전을 싣는다(lock 동일).
  • spring-cloud-context — @RefreshScope 금지(no-refresh-scope) fixture 용. Spring Cloud 는 production 에 없고 규칙은 애너테이션을 FQN 문자열로 참조한다. BOM 이 spring-cloud 좌표를 관리하지 않아 버전을 명시 고정한다.

빌드 설정

  • test JVM UTC 고정(-Duser.timezone=UTC) — RuntimeHealthLifecycleContractTest가 TimeZone.getDefault().getID() == "UTC"를 단언해, 호스트 로케일과 무관하게 타임스탬프 산술이 결정적이게 한다. production UTC 는 여기서 강제하지 않으며 container-runtime-contract(Dockerfile TZ=UTC)가 소유한다.
  • bootRun.workingDir = rootProject.projectDir — .env를 읽도록 Gradle 루트(저장소 루트)에서 실행한다.