Files
clean-architecture-backend-…/docs/mongodb/consumer-leaf-guide.md
DongHyeonka 24eb1be36d docs(mongodb): MongoDB 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: 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 문서의 파일 존재만 본다.
2026-11-07 17:29:57 +09:00

150 lines
7.7 KiB
Markdown

# 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").
전체 흐름:
```text
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`가 거부한다.
1. `modules.json`의 `modules`에 서비스 leaf를 추가한다. 플랫폼 leaf로 가는 edge를 여기서 연다.
```json
{
"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`를
같은 방식으로 받는다.
2. `app-bootstrap`의 `allowed_dependencies`에 `"adapter-outbound-persistence-note"`를 더한다.
`adapter-outbound-persistence-mongo`는 이미 들어 있다.
3. 서비스 leaf의 `build.gradle`:
```groovy
dependencies {
implementation project(':domain-core')
implementation project(':application-core')
implementation project(':adapter:outbound:persistence-mongo')
}
```
4. `app-bootstrap/build.gradle`에서 두 leaf를 켠다. 플랫폼 leaf 줄은 주석으로 이미 있다.
```groovy
runtimeOnly project(':adapter:outbound:persistence-mongo')
runtimeOnly project(':adapter:outbound:persistence-note')
```
5. 확인: 새 leaf의 `check`와 `architectureCheck`를 돈다. 아래 Gradle 경로는 서비스가 만든 leaf의 것이라
이 템플릿에는 없다.
```bash
./gradlew :adapter:outbound:persistence-note:check architectureCheck --console=plain
```
## 3. 서비스 leaf가 등록해야 하는 bean
자동 구성되는 `MongoCollectionProfileRegistry`는 **비어 있다**. 등록하지 않은 collection profile로
executor를 부르면 거부된다. 서비스 leaf가 자기 collection을 등록한 registry bean을 준다.
```java
@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`(`MongoQueryPolicy`
allowlist)로 만든다. 예시의 `_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.*`)을 쓴다.