Files
clean-architecture-backend-…/docs/mongodb/support-matrix.md
T
DongHyeonka 24eb1be36d docs(mongodb): MongoDB 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: 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 문서의 파일 존재만 본다.
2026-11-07 17:29:57 +09:00

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).