문제: core 계층(application·domain·shared-contract), app-bootstrap, composition, registry, build-logic, optional 빌드의 모듈 문서가 영어다. 세션이 처음 읽는 지역 규칙인데 소유자는 2026-11-07에 살아 있는 문서를 모두 한국어로 쓰기로 정했다. leaf CLAUDE.md 셋은 Spring Boot 버전을 4.0.0으로 복사해 두었는데 실제 버전(libs.versions.toml)과 다르다. 방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·표 구조는 원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을 가리키는 말로 바꾼다. 다른 문서·코드가 제목으로 가리키는 절(application-core의 Naming convention·Package ownership·Canonical use case shape·Allowed transactional shapes, shared-contract의 Responsibility·Forbidden, messaging의 발행 재시도 절)은 영어 원제를 괄호로 남겨 그 참조가 계속 찾아지게 한다. 참조하는 쪽을 고치는 것은 이 작업 범위 밖이다. 코드와 어긋난 주장은 코드에 맞춘다: TransactionPort 구현을 `adapter-persistence`에서 `adapter:outbound:persistence-jpa`의 `SpringTransaction`으로, registry README의 빈 의존 목록 예를 persistence-mongo(실제 목록은 application-core·shared-contract)에서 domain-core·shared-contract·messaging-core-api로 고친다. TemplatePackageOwnershipDocumentTest는 표 머리 문자열로 표를 찾으므로 머리 상수를 한국어 머리(`| 패키지 (...) |`)로 맞춘다. 표와 기계 사본을 대조하는 계약은 그대로다. 위험: 영어 원제를 괄호로 남긴 제목은 참조하는 문서가 한국어 제목으로 바뀌면 괄호를 지울 수 있다. 본문의 짧은 이력 번호(07-08, 06-01, 11-M9)는 뜻을 바꾸지 않으려고 그대로 옮겼다. 검증: python3 scripts/check-docs.py rc=0(번역한 파일의 language 줄 8개, number 줄 3개 지움), check-work-docs.py rc=0, --links(gates.md 범위) 깨진 링크 0, unittest discover scripts/tests 43개 통과.
8.9 KiB
8.9 KiB
app-bootstrap — 애플리케이션 진입점과 조립 루트
등록 정보
- 모듈 ID:
app-bootstrap - Gradle 경로:
:app-bootstrap - 이 모듈만 시험(Gradle 경로에서 나온 명령):
./gradlew :app-bootstrap:test --console=plain - 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은
src/gradle/libs.versions.toml이 정한다. - registry 정본:
src/config/architecture/modules.json.
패키지 루트: dev.caskeleton.bootstrap.
책임
- Spring Boot 진입점(
CaSkeletonApplication). - 런타임 설정과 로깅 시작.
- 모듈을 가로지르는 마지막 배선.
- 모든 모듈을 들여다보는 아키텍처 시험.
허용
- 이 모듈의 Gradle 의존성이 분명히 선언하고 아키텍처 registry가 허용한 런타임 leaf. 해석된 Gradle runtime 그래프가 런타임의 정본이다. 구성원 목록을 metadata에 다시 적지 않는다.
- Spring Boot 시작·런타임 의존성.
- 시험에서 ArchUnit.
금지
- 구체적인 업무 정책.
- bootstrap 아래에 직접 쓴 controller, 유스케이스, repository 어댑터, mapper.
- 업무 로직을 구현하는 설정 클래스.
application-core나domain-core포트를 구현하기. 포트를 구현하는 클래스는 의존성을 어떻게 설정했든 outbound 어댑터이고adapter/outbound/*leaf에 둔다 —CompositionRootBoundaryArchitectureTest가 예외 없이 강제한다.- 기동 실패를
throw new IllegalStateException(...)으로 내기.StartupFailures(adapter:outbound:support, 패키지support.startup:envValidation/profileMismatch/requiredAdapterDisabled/migrationFailed)를 써서 실패가 sysexits 종료 코드와 구조화된 로그 필드를 싣게 한다 —StartupFailureContractArchitectureTest가 강제한다. - 「운영 환경인가?」를 이 모듈 안에서 답하기. 저장소 전체의 profile 어휘는
dev.caskeleton.shared.runtime.RuntimeEnvironment가 가진다. src/test에서org.testcontainers에 의존하기. 실제 서비스를 쓰는 시험은src/integrationTest에 둔다.docs/testing/TESTING_STRATEGY.md를 본다.
패키지 배치
아래 규칙은 그것이 없어서 이 모듈의 리뷰 대상이 된 어긋남이 생겼기 때문에 있다
(docs/reviews/2026-09-07-app-bootstrap-module-code-review.md). capability의 절반은 autoconfigure/
아래, 절반은 패키지 루트에 있었다. Settings 클래스는 규칙 없이 settings/ 패키지와 각 기능
패키지에 나뉘어 있었다. 그리고 같은 분해 문제를 같은 leaf에서 두 가지로 풀었다 — Notification은 작은
설정 아홉 개로, Redis는 376줄 클래스 하나로.
- capability의 조립은 그 capability 자신의 모듈에 있다. 그 모듈의
AutoConfiguration.imports가 등록하고, 설정은 그 모듈의config/module-defaults/*.yml에 둔다. JPA(기동 guard, Flyway 전략, lock decorator, readiness,JpaActivationEnvironmentPostProcessor의 완전히 끄기 처리)는adapter:outbound:persistence-jpa, Redis(readiness)는adapter:outbound:cache-redis, 알림은composition:notification-platform이다. 모든 capability는build.gradle에서 주석 처리한runtimeOnly한 줄이다. 기본 조립은 web, 관측, core들, support, identifier다. 이 leaf는 capability 목록을 두지 않는다: 스위치 registry도, capability 사이 의존 검증기도, 켜기 endpoint도 없다. component scan은dev.caskeleton.bootstrap만 본다. web(WebAdapterAutoConfiguration,WebSecurityAutoConfiguration,WebMethodSecurityAutoConfiguration)과 support (OutboundSupportConfig)는 자기AutoConfiguration.imports로 들어온다.autoconfigure/<name>/에 남는 것은 모든 애플리케이션에 필요한 애플리케이션 조립인common(시계)뿐이다. outbox relay, 멱등성 executor, durable operation(유스케이스와/operationsendpoint, 07-08)은composition:outbox-relay,composition:idempotency,composition:durable-operation이다. 각각runtimeOnly한 줄로 고르고, 자기 포트가 생기기 전에는 아무것도 만들지 않는다. capability의 role → permission 대응은config/security.yml이 아니라 그 capability의config/module-defaults파일에 담긴다. 모든 조립 루트에 필요한 런타임 배선 — tracing, metric 계약 filter, domain-context 전파, 사용자 principal 가명화(PrivacySettings), actuator chain — 은composition:service-runtime이다. <Capability>Settings는settings/가 아니라 그 capability 옆에 둔다.settings/패키지는 어느 capability에도 속하지 않는 설정 —BootstrapSettings,RuntimeSafetySettings— 만 담는다. 이 설정은StrictSettingsBinder로 엄격하게 바인딩하고 scan하지 않는다. 로깅에는 settings record가 없다.logback-spring.xml이app.logging.*을 직접 읽고LoggingConfigurationRule이 Logback이 쓸 수 없는 값을 거절한다.runtime/은 애플리케이션 자체에 대한 guard를 담는다 — 비밀 값, 숫자 한계, 오류 상세 노출, 여러 인스턴스 조율, runtime profile 검사(RuntimeEnvironmentProfileValidator). capability 설정에 대한 guard(JPA OSIV·DDL·pool·TLS·vendor guard, Mongo 연결 출처 규칙, GraphQL 배포 모드 규칙)는 그 capability의 모듈과 함께 나간다. 그래야 capability가 있을 때만 정확히 존재한다.- 기동 실패 어휘는
adapter:outbound:support에 있다(support.startup: phase, 오류 코드, 예외,StartupFailures,StartupValidationContext,StartupOrder,ReadinessGroup,RuntimeWarnings). 그래서 capability 모듈은 이 leaf에 의존하지 않고 같은 방식으로 실패한다.runtime/startup/에는StartupFailureExceptionReporter만 남는다. - 환경만 보는 guard는
StartupRulebean이다(support.startup). 위반을 돌려주고, 유일한StartupRuleRunner가 다른 singleton이 생기기 전에 그것을 올린다(Environment, bean factory, 정적RequiredProductionSecrets의ObjectProvider만 받는static@Bean메서드로 선언한다. 모든 profile에서 runner는 어떤 규칙을 돌리기 전에 규칙마다, 그리고RequiredProductionSecrets마다 하나씩 만든다. 그중 하나가 만드는 다른 bean이 있으면 그 이름을 대며 기동을 실패시킨다. runtime 클래스에@Value/@Autowired/@Inject/@Resource멤버,@PostConstruct/@PreDestroy콜백,@ConfigurationProperties바인딩이 있는 것도 이름을 대며 실패시킨다 — 그런 것은 post-processor보다 먼저 만들어져 값이 비어 있게 된다). 다른 bean이 필요한 guard는 bean으로 남는다. capability의 운영 비밀 값은 그 capability의 것이다: 그 모듈이RequiredProductionSecretsbean을 내놓고,SecretSourceValidator는 어떤 role이 있는지 모르는 채로 이름을 검사한다.
분해 기준
취향에 맡기지 않고 적어 둔다. 「충분히 길다고 느꼈다」가 같은 질문에 두 가지 답을 낳았기 때문이다.
@Configuration하나는 조립 관심사 하나를 담는다. 대략@Bean메서드 여덟 개를 넘거나, 서로 관계없는 포트 묶음 둘을 조립하게 되면 — 둘 중 먼저 오는 때에 — 나눈다.@ConfigurationProperties클래스 하나는 capability namespace 하나를 가진다.- 설정이 둘 이상 필요한 capability는 루트 클래스를 둔다. 루트가
enabled조건,@EnableConfigurationProperties, 관심사별 클래스의@Import를 가진다. 아무것도 scan하지 않는다: 조건이 걸린 루트에서@Import해야enabled=false가 권고가 아니라 실제로 끄는 스위치가 된다.cache-redis의capability/RedisCapabilityConfig가 참조 예다. 다시 쓸 Spring 조립을 가진 optional 어댑터 capability는 자기 루트를 내놓는다. 알림은adapter:outbound:notification의NotificationPlatformAutoConfiguration과composition:notification-platform의NotificationApplicationCompositionAutoConfiguration을 쓴다. JPA는adapter:outbound:persistence-jpa의 package-privatePersistenceJpaAutoConfiguration,PersistenceJpaRuntimeConfig,startup.JpaStartupAutoConfiguration을 쓰고, 이 모듈은 기본 조립에 없다(build.gradle의// runtimeOnly project(':adapter:outbound:persistence-jpa')). Mongo도 같은 규칙을 따른다: persistence-mongo leaf가 MongoRootAutoConfiguration과 그 내부 health bridge를 가지고, bootstrap은 Mongo 전용 운영 health 설정을 가지지 않는다. - 나눈 capability의 공용 도우미는
*Util바구니가 아니라 하는 일을 이름으로 단 자기 타입을 가진다 —cache-redis의capability/RedisKeys가 참조 예다.
테스트
cd src
./gradlew :app-bootstrap:test
./gradlew verifyCleanArchitectureDependencies