문제: 앞 커밋이 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
150 lines
7.7 KiB
Markdown
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.*`)을 쓴다.
|