Files
clean-architecture-backend-…/docs/mongodb/consumer-leaf-guide.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 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
2026-11-11 22:15:42 +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/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.*`)을 쓴다.