# 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"). 전체 흐름: ```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 목록과 허용 의존 방향의 원본은 `gradle/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. `src/bootstrap/app/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.*`)을 쓴다.