문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
7.7 KiB
Mongo 소비 leaf 등록 절차
파생 서비스가 adapter:outbound:persistence-mongo를 실제로 쓰려면 자기 Mongo 어댑터 leaf를 하나
만든다. 이 leaf(이하 "플랫폼 leaf")는 client·template·정책·실패 분류를 주고, document·repository·
mapper·port 구현은 서비스 leaf가 가진다. 플랫폼 leaf에는 예시 도메인을 production으로 넣지 않는다
(src/adapter/outbound/persistence-mongo/AGENTS.md "Forbidden").
전체 흐름:
domain-core (Note) application-core (NoteStore port)
\ /
adapter:outbound:persistence-note ← 서비스가 새로 만드는 leaf
NoteDocument / NoteDocumentMapper / NoteDocumentRepository / MongoNoteStore
|
| implementation
v
adapter:outbound:persistence-mongo ← 플랫폼 leaf (executor, 실패 분류, 정책)
^
| runtimeOnly (둘 다)
app-bootstrap
1. 동작하는 예시
예시 한 벌이 플랫폼 leaf의 테스트 소스에 있다. mongoStableContractTest(그래서 check)에서
컴파일되고 실행되므로 API가 바뀌면 예시도 같이 깨진다.
| 역할 | 예시 타입 | 실제 서비스에서 둘 곳 |
|---|---|---|
| 도메인 타입 | Note |
domain-core |
| outbound port, 도메인 예외 | NoteStore, NoteStore.NoteAlreadyExistsException |
application-core |
| 저장 형태 | NoteDocument (@Document, @Id, @Field) |
서비스 Mongo leaf |
| 변환 | NoteDocumentMapper |
서비스 Mongo leaf |
| collection 접근 | NoteDocumentRepository (DefaultMongoImperativeExecutor 사용) |
서비스 Mongo leaf |
| port 구현, 예외 변환 | MongoNoteStore |
서비스 Mongo leaf |
| 실행 확인 | MongoNoteStoreExampleTest |
서비스 Mongo leaf 테스트 |
위치: src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/example/.
testFixtures가 아니라 테스트 소스에 둔 이유: testFixtures는 소비 leaf의 테스트 classpath에 그대로 올라가는 variant다. 예시 타입이 거기 있으면 API처럼 import된다. 테스트 소스는 아무 데도 export되지 않는다.
2. 레지스트리와 Gradle에 leaf 등록
leaf 목록과 허용 의존 방향의 원본은 gradle/modules.json이다. 레지스트리에 없는 edge는
verifyCleanArchitectureDependencies가 거부한다.
-
modules.json의modules에 서비스 leaf를 추가한다. 플랫폼 leaf로 가는 edge를 여기서 연다.{ "id": "adapter-outbound-persistence-note", "gradle_path": ":adapter:outbound:persistence-note", "source_path": "src/adapter/outbound/persistence-note", "allowed_dependencies": [ "domain-core", "application-core", "adapter-outbound-persistence-mongo" ] }같은 모양의 선례:
adapter-outbound-persistence-notification이adapter-outbound-persistence-jpa를 같은 방식으로 받는다. -
app-bootstrap의allowed_dependencies에"adapter-outbound-persistence-note"를 더한다.adapter-outbound-persistence-mongo는 이미 들어 있다. -
서비스 leaf의
build.gradle:dependencies { implementation project(':domain-core') implementation project(':application-core') implementation project(':adapter:outbound:persistence-mongo') } -
src/bootstrap/app/build.gradle에서 두 leaf를 켠다. 플랫폼 leaf 줄은 주석으로 이미 있다.runtimeOnly project(':adapter:outbound:persistence-mongo') runtimeOnly project(':adapter:outbound:persistence-note') -
확인: 새 leaf의
check와architectureCheck를 돈다. 아래 Gradle 경로는 서비스가 만든 leaf의 것이라 이 템플릿에는 없다../gradlew :adapter:outbound:persistence-note:check architectureCheck --console=plain
3. 서비스 leaf가 등록해야 하는 bean
자동 구성되는 MongoCollectionProfileRegistry는 비어 있다. 등록하지 않은 collection profile로
executor를 부르면 거부된다. 서비스 leaf가 자기 collection을 등록한 registry bean을 준다.
@Bean
MongoCollectionProfileRegistry mongoCollectionProfileRegistry() {
return MongoCollectionProfileRegistry.builder()
.register(NoteDocument.COLLECTION, NoteDocument.COLLECTION)
.build();
}
여러 서비스 leaf가 각자 collection을 가지면 registry bean은 하나여야 하므로 composition(보통
app-bootstrap)에서 합친다.
DefaultMongoImperativeExecutor는 자동 구성 bean이다. 서비스 leaf는 그것을 주입받아
NoteDocumentRepository처럼 감싼다.
4. 예외 변환
- executor는 driver·Spring 실패를 한 번만 플랫폼 예외로 바꾼다:
MongoDuplicateKeyException,MongoTimeoutException,MongoWriteConcernException,MongoServerSelectionException등(dev.caskeleton.adapter.outbound.mongo.api.error). - port 구현은 port가 약속한 실패만 도메인 예외로 바꾼다. 예시에서는
MongoDuplicateKeyException→NoteAlreadyExistsException하나다. - 나머지는 그대로 내보낸다. 플랫폼 예외는
outcome()·ambiguous()로 "쓰기가 됐는지 모름"을 알려 준다. 이것을 일반 도메인 예외로 감싸면 호출자가 재시도해도 되는지 판단할 근거가 사라진다. - 트랜잭션은
MongoTransactionRetryCoordinator로 실행한다. 본문의TransientTransactionError는 새 세션에서 본문을 다시 실행하고, commit 결과를 모르면 commit만 재시도한 뒤MongoTransactionCommitUnknownException으로 알린다. 본문은 재실행될 수 있으므로 본문 안에서 외부 호출(메시지 발행, HTTP)을 하지 않는다.
5. 정책을 우회하는 경로 — 쓰기 전에 알 것
| 경로 | 받는 것 | 잃는 것 |
|---|---|---|
DefaultMongoImperativeExecutor (+ MongoAtomicOperationsTemplate, MongoBulkExecutor) |
operation 이름, collection profile 확인, consistency, deadline, 관측, 실패 변환 | 없음. 기본 경로 |
Spring Data MongoRepository (adapter-local) |
짧은 CRUD 코드 | 위 전부. 실패가 Spring DuplicateKeyException 등으로 온다. derived query는 MongoQueryPolicy를 거치지 않는다. deadline·consistency profile이 붙지 않는다 |
MongoTemplate / MongoClient 직접 주입 |
모든 명령 | 위 전부 + collection 범위 확인 |
MongoRepository는 adapter leaf 안에서만 허용된다 (MongoRepositoryArchitectureRules.allowedRepositorySuperTypes). 고르면 예외 변환과 timeout을 서비스 leaf가 직접 책임진다. 플랫폼 공통 CRUD base(CommonMongoRepository등)는 만들지 않는다.- 사용자 입력으로 조건이 바뀌는 동적 조회는
PolicyAwareMongoQueryBuilder(MongoQueryPolicyallowlist)로 만든다. 예시의_id조회처럼 adapter 코드가 고정한 조건은Query를 직접 써도 된다. - inbound adapter(controller 등)는
MongoTemplate·MongoClient를 갖지 않는다. 서비스 leaf 테스트에서 플랫폼 testFixtures의MongoAccessRules.noMongoAccessFrom(...)으로 확인할 수 있다 (testImplementation testFixtures(project(':adapter:outbound:persistence-mongo'))).
6. 연결 설정
URI만 주는 배포(SPRING_MONGODB_URI)는 유한 timeout·pool 기본값을 받는다. 값과 바꾸는 법은
src/adapter/outbound/persistence-mongo/README.md의 SPRING_MONGODB_URI 예시 바로 아래 문단과 MongoUriOnlyClientDefaults에 있다.
production은 typed profile(app.persistence-mongo.platform.profiles.*)을 쓴다.