문제: 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 문서의 파일 존재만 본다.
6.7 KiB
MongoDB 플랫폼 — 지원 매트릭스
설계서 §4. 이 파일은 플랫폼이 우연히 돌아가는 환경이 아니라 인증한 환경을 적는다. 이 표에 없는 구성은 누군가 그 구성으로 게이트를 돌리고 행을 더하기 전까지 지원하지 않는다.
1. 런타임 기준
| 구성 요소 | 버전 | 정책 |
|---|---|---|
| Java | 21 | 저장소 런타임 기준. |
| Spring Boot | src/gradle/libs.versions.toml의 springBoot |
BOM이 관리한다. driver를 따로 덮어쓰는 것은 금지한다. |
| Spring Data MongoDB | Boot BOM이 정한다 | repository와 MongoTemplate 통합. |
| MongoDB Java Driver | Boot BOM이 정한다 | 모듈에서 직접 고정하지 않는다. |
| Micrometer | Boot BOM이 정한다 | driver 자체 관측. |
| Testcontainers | Boot BOM이 정한다 | replica set, failover, migration, compatibility lane. |
BOM이 정한 실제 버전은 leaf의 잠금 파일 src/adapter/outbound/persistence-mongo/gradle.lockfile에 있다.
버전을 이 표에 옮겨 적지 않는다. 옮겨 적은 숫자는 다음 업그레이드에서 틀린 글이 된다.
설계의 기준은 Spring Boot 4.1 계열 / Spring Data MongoDB 5.1 계열이다. 이 저장소는 Spring Boot 4.0 계열 / Spring Data MongoDB 5.0 계열이므로, 플랫폼은 둘에 공통인 API 면만 쓴다. repository-adaptation.md §3을 본다.
2. 서버 버전
| Lane | 버전 | 고정한 이미지(key) | Gradle task |
|---|---|---|---|
| 주 인증 | MongoDB 8.0 | mongo-8 |
mongoReplicaSetTest, mongoFailoverTest |
| 호환성 | MongoDB 7.0 | mongo-7 |
mongoCompatibilityTest |
| 네트워크 장애 주입 | — | toxiproxy |
mongoFailoverTest |
이미지는 고정하고 latest를 쓰지 않는다. 바뀌는 tag를 쓰면 인증 결과는 행에 적은 버전이 아니라 그날 아침
받은 무언가를 설명한다. 이미지의 정본은 src/config/testing/container-images.properties다. 표의 key마다
digest와 그 digest의 tag(주석)가 거기 있다. patch 버전은 이 표에 옮겨 적지 않는다. 새 patch 버전을 시험할 때는
-PmongoPrimaryImage=… / -PmongoCompatibilityImage=…로 덮어쓰고, 게이트가 통과하면 그 파일을 고친다.
MongoVersionMatrix.standard()가 이 표의 기계용 형태다. 그 밖의 버전은 certifies()에서 실패한다.
3. 토폴로지
| 토폴로지 | 상태 | 인증하는 것 | 인증하지 않는 것 |
|---|---|---|---|
| Standalone | smoke만 | 기본 CRUD와 매핑. | 운영 profile이 아니고 Stable 릴리스 증거로 세지 않는다(D-03). Standalone 서버 위의 운영 profile이나 platform.transactions=true는 MongoStartupValidator가 시작할 때 거부한다. |
| 노드 하나짜리 replica set | 로컬 기본값(D-02) | transaction, retryable write, change stream — 운영과 같은 의미. | 선출. 노드 하나짜리 set은 선출을 하지 않으므로 여기서는 failover 동작을 시험하지 않는다. |
| 노드 세 개짜리 replica set | Stable 운영 게이트 | 위의 모든 것과 primary failover, commit 결과를 모를 때의 처리. | shard 라우팅. |
| Sharded cluster | Advanced 게이트 | shard key 라우팅 분류, scatter-gather 거부, admin plane 작업. |
Stable 게이트에 들지 않는다. |
| Atlas / provider 관리형 | 인증 안 함 | 실제 대상 배포에서의 암호화는 도입하는 쪽이 만들 증거다. | 검색과 vector 검색은 이 leaf에 구현이 없다. native $search 명령은 등록한 D3 연산으로 PolicyAwareMongoNativeGateway를 거쳐야만 갈 수 있다. |
4. Stable API와 client 세대
| Plane | Stable API | 용도 |
|---|---|---|
| D1 표준 문서 영속성 | V1, apiStrict=true |
repository, 타입 있는 query, atomic update, 낙관적 revision. |
| D2 고급 문서 연산 | V1, apiStrict=true |
MongoTemplate, transaction, bulk, aggregation, keyset cursor. |
| D3 명시적 Mongo capability | strict 아님 | native BSON, CSFLE/QE, shard를 아는 연산 — 각각 등록한 capability 뒤에 있다. |
| D4 Admin plane | strict 아님 | collection, validator, index, migration, shard, repair 명령. credential도 client도 따로다. |
D3는 날것의 client로 빠지는 출구가 아니다. 모든 호출은 이 순서대로 지나간다: capability 등록 → database profile → collection 허용 목록 → 연산 이름 → timeout → 일관성 profile → 결과 상한 → trace → 가리기 → 명령 분류 → D4 거부.
5. Validation action
Stable validation action은 error와 warn이다. errorAndLog는 7.0이나 8.0에서 Stable 계약에 들지
않고, MongoValidatorDescriptor가 거부한다.
6. 명시적으로 지원하지 않는 것
설계 §3.4에 따라 아래는 하나도 제공하지 않는다. 하나라도 더하는 것은 기능 요청이 아니라 설계 변경이다.
- 범용
CommonMongoRepository<T, ID>. - 실행 중 임의의
runCommand. - 운영에서 index 자동 생성.
- Standalone 운영 계약.
- 정확한 업무 일정 도구나 유일한 접근 제어로서의 TTL.
- 날것의 change event를 외부 업무 통합 이벤트로 내보내기.
- 새 파일의 정본으로서의 GridFS.
- 오래 사는 BSON schema로서의 Java FQCN.
- 상한 없는 skip 페이지 나누기, 상한 없는 aggregation pipeline, 상한 없는 regex, 상한 없는 결과.
7. Capability 등급
| 등급 | Capability | 켜는 법 |
|---|---|---|
| Stable, 자동 구성 | 매핑과 BSON converter, 명령형 실행, atomic update, bulk 부분 결과, 일관성 profile, 재시도/변환, 연산 예산, 관측, 타입 있는 client profile, 시작 검증, health | app.persistence-mongo.enabled=true일 때 bean을 등록한다. |
| Stable, 라이브러리 API | transaction, causal session, 낙관적 revision, query builder와 keyset 페이지 나누기, aggregation executor, schema/index/validator manifest와 diff, TTL 계약, GeoJSON, migration runner, admin plane, native capability gateway | 도입하는 쪽의 어댑터 leaf가 이 leaf를 implementation으로 받고 타입을 만든다. |
| Advanced, 라이브러리 API | shard를 아는 query와 shard admin, CSFLE, Queryable Encryption(equality/range), shared collection tenancy 정책 | 위와 같고, 그 capability를 켠 flag의 MongoAdvancedCapabilityGuard가 더 필요하다. 설정 속성은 없다. |
| Experimental, 라이브러리 API | tenant마다 database client registry와 migration coordinator, reshard 승인 | Advanced와 같다. 승격에는 ADR-MONGO-ADV-001의 증거가 더 필요하다. |
검색, vector 검색, time series, GridFS 호환은 구현 없는 interface였고 2026-09-25에 지웠다
(docs/capability-status.md).