문제: docs/mongodb 아래 살아 있는 문서 14개가 영어였고(문서 검사 language 예외), 몇 가지 주장이 지금 코드와 달랐다. - repository-adaptation.md가 registry의 leaf 수(19)와 Spring Boot 버전을 옮겨 적었다(number 예외 두 줄). - 같은 문서와 advanced/signoff/README.md가 scripts/verify-mongodb-platform.sh· verify-mongodb-advanced.sh를 2026-08-15에 지웠다고 했다. 두 스크립트는 지금도 있고 lane을 돌린다. - testkit을 `testkit` source set에 둔다고 했다. 지금은 `testFixtures`(ADR-BUILD-001)와 `mongoProviderTestkit`이다. `…mongo.architecture`도 main이 아니라 testFixtures에 있다. - ArchUnit 규칙 이름 `stableNeverDependsOnAdvanced`·`productionNeverDependsOnTestkit`은 없다. 실제는 MongoModuleBoundaryTest의 `noStablePackageDependsOnAnAdvancedCapability`· `noProductionPackageDependsOnTheTestkit`이다. - support-matrix.md의 Boot·Spring Data·driver·Micrometer·Testcontainers 버전이 lockfile과 달랐다(예: driver 5.6.1 → 5.6.5). - consumer-leaf-guide.md가 템플릿에 없는 Gradle 경로를 인라인 코드로 적었다 (reference 예외). - document-modeling-guide.md가 타입 metadata를 bson-mapping-guide §4로 가리켰다(§5). 고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 버전과 leaf 수는 숫자 대신 정본(src/gradle/libs.versions.toml, registry, gradle.lockfile, container-images.properties)을 가리킨다. 서비스가 만들 leaf의 확인 명령은 다른 단계와 같이 코드 블록에 두고 템플릿에 없는 경로라고 밝힌다. 버린 대안: support-matrix 버전을 lockfile 값으로 고쳐 적기. 다음 업그레이드에서 다시 틀리고, 같은 시간에 도는 의존성 세션과 같은 줄을 고치게 된다. 위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다. 설계 번호(§, D-xx)는 그대로 두었다. 검증: python3 scripts/check-docs.py rc=0(이 폴더 language·reference·number 예외 줄 0). docs/mongodb를 읽는 테스트는 주석뿐이다(`grep -rn 'docs/mongodb' src --include=*.java` — package-info.java·MongoModuleBoundaryTest 주석). scripts/verify-mongodb-advanced.sh는 advanced 문서의 파일 존재만 본다.
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/CLAUDE.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 목록과 허용 의존 방향의 원본은 src/config/architecture/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') } -
app-bootstrap/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.*)을 쓴다.