문제: 모듈 README·AGENTS·매뉴얼·Javadoc이 옮기거나 이름을 바꾼 타입,
지운 샘플, 다른 repo로 옮긴 플랫폼을 그대로 가리켰다.
- 옮기거나 바꾼 타입: OutboxConfig(지금 :composition:outbox-relay의
OutboxRelayAutoConfiguration), IdempotencyProviderSelectionConfig(지금
:composition:idempotency의 IdempotencyAutoConfiguration),
TracingProperties·GraphQlPlatformProperties(지금 *Settings), SecretSource
(지금 application-core SecretSourcePort), JsonNullableModule(지금
JsonNullableJackson3Module), PeriodTest·OutboxEventIdFactory(샘플과 함께
지움).
- 지운 샘플: SampleDemoProfilesStartupSystemTest, 「sample 테스트」,
IdempotencyAutoConfiguration·ManagementSecurityConfig Javadoc의 샘플.
- 옮긴 플랫폼: graphql AGENTS·README가 messaging 플랫폼과 「두 패턴 공존」을
적었지만 그 플랫폼은 2026-11-08 messaging-library로 옮겼다. gRPC 문서는
grpc-library로 옮긴 플랫폼을 「vendored」·「벤더 starter」로 불렀다.
- leaf CLAUDE.md를 가리키던 곳(지금 AGENTS.md), 복사한 숫자(httpclient
java 파일 수, graphql systemTest 수), manual 06의 registry 머리말 옛 영어 인용.
고른 방법: 문장이 가리키는 대상만 지금 이름으로 바꾼다. 동작 설명은 그대로
둔다. 숫자는 지운다(레지스트리·빌드가 정한다).
검증:
- 노트북: check-docs.py rc=0. check-work-docs.py는 main의 operate.md 151줄
때문에만 rc=1.
- desktop(--no-build-cache, 트리 310eb524): 이 문서들을 읽는 시험
(:app-bootstrap:documentContractTest, repositoryContractTest —
DeveloperExperienceContractTest 포함, MongoNamespaceContractTest,
AwsQualificationClaimHonestyTest)과 Javadoc을 고친 두 leaf의
compileJava·spotlessCheck. 134건 실패 0, skip 1.
520 lines
44 KiB
Markdown
520 lines
44 KiB
Markdown
# app-bootstrap — 설계 결정 참조
|
|
|
|
애플리케이션 진입점이자 합성 루트(composition root) 모듈. 패키지 루트: `dev.caskeleton.bootstrap`.
|
|
|
|
이 모듈은 비즈니스 로직을 담지 않는다. Spring Boot 기동, 런타임 설정 바인딩, 기본 runtime
|
|
모듈 간 최종 와이어링, 그리고 composition classpath를 대상으로 한 중앙 아키텍처 테스트만 둔다.
|
|
모든 leaf의 프로젝트 edge는 JSON registry를 읽는 Gradle 방향 게이트가 별도로 검사한다. 허용/금지 의존, 책임 범위, 테스트 명령 같은 **모듈 규칙**의
|
|
SSOT 는 [AGENTS.md](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](../../../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 시작 파이프라인](#runtimestartup--fail-fast-시작-파이프라인과-시작-실패-분류)
|
|
- [runtime — 시크릿 소스 선택과 런타임 안전 가드](#runtime--시크릿-소스-선택과-런타임-안전-가드)
|
|
- [concurrency — 도메인 컨텍스트 전파 (composition:service-runtime으로 이동)](#concurrency--도메인-컨텍스트-전파-compositionservice-runtime으로-이동)
|
|
- [async — 비동기 executor 컨텍스트 전파와 포화 처리](#async--비동기-executor-컨텍스트-전파와-포화-처리)
|
|
- [idempotency — 멱등성 executor 조립 (composition:idempotency로 이동)](#idempotency--멱등성-executor-조립-compositionidempotency로-이동)
|
|
- [outbox — 트랜잭셔널 아웃박스 릴레이 (composition:outbox-relay로 이동)](#outbox--트랜잭셔널-아웃박스-릴레이-compositionoutbox-relay로-이동)
|
|
- [logging — 로그 시크릿 마스킹·샘플링·가명화](#logging--로그-시크릿-마스킹샘플링가명화)
|
|
- [metrics·management/security·tracing (composition:service-runtime으로 이동)](#metricsmanagementsecuritytracing-compositionservice-runtime으로-이동)
|
|
- [settings — @ConfigurationProperties 검증 정책](#settings--configurationproperties-검증-정책)
|
|
- [build.gradle — 의존성 구성 근거](#buildgradle--의존성-구성-근거)
|
|
|
|
---
|
|
|
|
## 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 / 클라우드 시크릿 매니저)를 인터페이스 뒤로 숨기고, 위험한
|
|
런타임 설정값은 기동 시점에 막는다.
|
|
|
|
### SecretSourcePort
|
|
- **시크릿 해석을 인터페이스 한 겹 뒤로 숨긴 backend seam 이다.** 포트는 application-core
|
|
`dev.caskeleton.application.secret`에 있다. 시크릿이 필요한 코드는 이 인터페이스에만 의존하고,
|
|
실제 백엔드(env / Vault / AWS Secrets Manager / GCP Secret Manager)는
|
|
`SecretSourceFactory`가 설정값으로 고른다. 설정과 구현 선택을 한 factory에 모으는 패턴이다.
|
|
백엔드를 추가하는 비용이 "새 `SecretSourcePort` 구현 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 값 + `SecretSourcePort` 구현 + factory
|
|
case"임을 코드에서 바로 읽히게 했다(rate-limit algorithm enum 패턴과 동일).
|
|
|
|
### SecretSourceSettings
|
|
- **설정이 없어도 동작하는 기본값(ENVIRONMENT)을 박았다.** 스켈레톤은 별도 설정 없이 바로 부팅돼야
|
|
하므로, `strategy`가 `null`이면 `ENVIRONMENT`로 보정한다. 백엔드 교체는 코드 수정이 아니라 설정
|
|
한 줄로 끝난다.
|
|
|
|
### SecretSourceConfig
|
|
- **시크릿 백엔드와 그 시작 가드를 composition root 에서만 와이어링한다.** `SecretSourceFactory`로
|
|
선택된 `SecretSourcePort` 구현(기본 `ENVIRONMENT`)과, 그것을 통해 필수 시크릿을 검증하는
|
|
`SecretSourceValidator`를 빈으로 노출한다. 검증기를 Spring 스테레오타입 없는 일반 클래스로 둔
|
|
이유는 단위 테스트 가능성을 지키기 위함이고, 이 config 가 유일한 production 와이어링이다.
|
|
- **`RuntimeSafetyConfig`와 일부러 분리했다.** 시크릿 계약은 secrets-config-source-contract 가
|
|
소유하고, 런타임 안전 토글은 env-driven-runtime-configuration 이 소유한다. 소유 경계를 코드 구조로
|
|
보존하기 위해 한 config 로 합치지 않았다.
|
|
|
|
### SecretSourceFactory
|
|
- **유일한 확장 지점을 `switch` 하나로 모았다.** 새 백엔드는 `SecretSourceStrategy` 값 +
|
|
`SecretSourcePort` 구현 + 이 `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](../service-runtime/README.md).
|
|
|
|
## 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](../idempotency/README.md).
|
|
|
|
## 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](../outbox-relay/README.md).
|
|
|
|
## 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](../service-runtime/README.md).
|
|
|
|
## 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 루트(저장소 루트)에서
|
|
실행한다.
|