문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지 크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의 500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본 (TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR 테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로 만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져 객체 저장소 lane이 돌지 않았다. 방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은 결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD, S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한). MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자· mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고, scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과 왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와 결정은 리뷰 README 14절에 있다. 위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서 H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC· WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체, 샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개 (composition:durable-operation, adapter:inbound:messaging)와 새 마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1, grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면 실패한다(runbook에 확인 쿼리). 검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함 전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절 BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션 기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가, 샘플 Idempotency-Key 오류 코드 변경.
145 lines
7.5 KiB
Markdown
145 lines
7.5 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. 확인: `./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.*`)을 쓴다.
|