Files
clean-architecture-backend-…/docs/mongodb/repository-adaptation.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

11 KiB

MongoDB 문서 영속성 플랫폼 — 저장소 적응 계약

설계서: docs/design/2026-08-11-mongodb-document-persistence-platform-design.md Stable 계획서: docs/history/plans/2026-08-11-mongodb-document-persistence-platform-implementation-plan.md Advanced 계획서: docs/history/plans/2026-08-11-mongodb-advanced-capabilities-expansion-plan.md

설계 패키지는 자기 모듈 root(modules/mongodb)와 root package(io.backend.skeleton.mongodb)를 계약이 아니라 구현 가정으로 적었다. 이 파일은 그 가정한 배치를 이 저장소에 어떻게 옮겼는지 적은 유일한 기록이다. 바뀐 것은 경로, 빌드 DSL, 조립 루트의 소유뿐이다. 공개 계약, 정책 순서, 오류 의미는 명세대로 구현했다.

1. 모듈 배치가 다른 이유

설계는 modules/mongodb/ 아래에 Stable Gradle 프로젝트 19개, modules/mongodb-advanced/ 아래에 Advanced 프로젝트 12개를 가정한다. 이 저장소는 Clean Architecture 템플릿이고, 닫힌 쪽으로 실패하는 registry (src/config/architecture/modules.json)가 Gradle 프로젝트 목록을 정한다. src/settings.gradle이 registry에 있는 프로젝트만 포함하고, verifyCleanArchitectureDependencies가 허용하지 않은 의존을 막는다. 설계의 모듈마다 Gradle 프로젝트를 만들면 AGENTS.md의 HARD-STOP 5번(registry·Gradle 의존성 검증 위반)에 걸린다.

그래서 설계의 모듈 31개는 등록된 leaf :adapter:outbound:persistence-mongo 안의 package 경계가 된다. docs/httpclient/repository-adaptation.md가 먼저 세운 방식을 따른다. 설계의 모듈 의존 표(§6.3)는 MongoModuleBoundaryTest가 닫힌 edge 행렬로 강제한다.

  • 최상위 package마다 import해도 되는 package를 선언한다.
  • 행렬과 실제 트리가 정확히 같은지 비교한다.
  • 관측한 edge는 모두 행렬에 있어야 한다.

금지된 edge는 Gradle 의존이 빠졌을 때와 똑같이 빌드를 실패시킨다. 아무도 등록하지 않은 새 package도 그렇다.

예전에는 이 문서의 주장이 테스트보다 강했다. 규칙은 역방향 의존 몇 개만 막고 나머지는 말하지 않았다. 그래서 설계의 DAG 밖의 edge가 있었고 통과했다. geo → imperative가 그중 하나다. 지금은 그런 edge를 지우지 않고 행렬에 선언했다. 하나하나가 코드가 실제로 기대는 결합이다. 적어 두는 이유는 다음 edge가 사고가 아니라 결정이 되게 하려는 것이다.

2. Package 대응

Root package: io.backend.skeleton.mongodb → dev.caskeleton.adapter.outbound.mongo.

2.1 Stable 모듈

설계 모듈 저장소 package
mongodb-core-api …outbound.mongo.api (+ .capability, .consistency, .error, .mapping, .observation, .profile, .schema)
mongodb-spring-data …outbound.mongo.mapping (+ .type), …outbound.mongo.failure
mongodb-imperative …outbound.mongo.imperative (+ .atomic, .bulk, .revision)
mongodb-query …outbound.mongo.query (+ .budget, .pagination)
mongodb-aggregation …outbound.mongo.aggregation
mongodb-transaction …outbound.mongo.transaction (+ .retry, .session)
mongodb-index-schema …outbound.mongo.schema (+ .index, .manifest, .model, .ttl, .validation)
mongodb-geospatial …outbound.mongo.geo
mongodb-migration-core …outbound.mongo.migration
mongodb-migration-flamingock …outbound.mongo.migration.flamingock
mongodb-observability …outbound.mongo.observation
mongodb-security …outbound.mongo.security (+ .admin), …outbound.mongo.nativecap
mongodb-spring-boot-starter …outbound.mongo.autoconfigure
mongodb-testkit-core …outbound.mongo.testkit.mapping, .compat, .performance (testFixtures source set)
mongodb-testkit-replicaset …outbound.mongo.testkit.rs (testFixtures, 컨테이너 fixture는 mongoProviderTestkit source set)
mongodb-testkit-failover …outbound.mongo.testkit.failover (testFixtures, 컨테이너 fixture는 mongoProviderTestkit source set)
mongodb-testkit-migration …outbound.mongo.testkit.migration (testFixtures source set)

…outbound.mongo.architecture는 설계에 짝이 없다. testFixtures source set에 있고, @MongoOperation 표시 annotation과, 파생 서비스가 자기 document·repository 코드에 적용하는 재사용 ArchUnit 규칙 묶음 (MongoRepositoryArchitectureRules)을 가진다.

2.2 Advanced 모듈

설계 모듈 저장소 package
mongodb-sharding …outbound.mongo.advanced.sharding (+ D4 shard plane용 .admin)
mongodb-csfle …outbound.mongo.advanced.encryption.csfle
mongodb-queryable-encryption …outbound.mongo.advanced.encryption.qe
mongodb-tenancy-shared …outbound.mongo.advanced.tenancy.shared
mongodb-tenancy-database …outbound.mongo.advanced.tenancy.database
mongodb-testkit-sharded …outbound.mongo.testkit.sharded (testFixtures source set)

mongodb-timeseries, mongodb-search, mongodb-vector-search, mongodb-gridfs-compat, mongodb-testkit-atlas는 이제 package가 없다. 각각 구현 없는 operations interface와 그것을 매개변수로 채우던 descriptor뿐이었고, 2026-09-25에 지웠다(docs/capability-status.md).

설계의 「Stable 모듈은 Advanced 모듈에 의존하지 않는다」 규칙은 ArchUnit 테스트로 남았다 (MongoModuleBoundaryTest의 noStablePackageDependsOnAnAdvancedCapability). 모든 Advanced 진입점은 MongoAdvancedCapabilityGuard를 받고, 그 MongoAdvancedCapabilityFlags가 해당 capability를 켜지 않았으면 생성을 거부한다. flag 뒤에 설정 속성은 없다. Advanced 타입은 라이브러리 API이고, 그것을 만드는 도입 측 어댑터가 guard를 만든다.

3. 그 밖에 일부러 바꾼 것

설계 가정 저장소 현실 적응
modules/mongodb* 아래 Gradle Kotlin DSL Groovy DSL, root build.gradle convention, LockMode.STRICT 잠금 의존성은 src/adapter/outbound/persistence-mongo/build.gradle에 선언하고 gradle.lockfile을 다시 만들었다.
mongodb-spring-boot-starter는 앱이 의존하는 별도 모듈 modules.json이 adapter-outbound-persistence-mongo에 명시적 프로젝트 경계를 준다. 런타임 편입은 leaf별 registry 필드가 아니라 해석한 런타임 classpath에서 정해진다 autoconfigure package는 leaf 안에 두고 leaf 자신의 META-INF/spring/…AutoConfiguration.imports로 등록한다. httpclient 선례와 다르다. leaf를 실제로 조립하는지는 의존성 게이트와 런타임 편입 게이트가 정한다.
Spring Boot 4.1 / Spring Data MongoDB 5.1 기준 저장소 기준은 Spring Boot 4.0 계열 / Spring Data MongoDB 5.0 계열이다. 정확한 버전은 src/gradle/libs.versions.toml의 springBoot와 leaf의 gradle.lockfile이다 플랫폼은 둘에 공통인 Spring Data MongoDB API 면만 쓴다. 5.1에만 있는 타입은 참조하지 않는다. 실제 고정 버전은 support matrix가 가리킨다.
MongoRetryScope는 mongodb-transaction에 있다 mongodb-spring-data의 실패 변환기가 재시도 범위를 분류해야 하는데 mongodb-transaction에 의존할 수 없다 MongoRetryScope는 두 package가 이미 의존하는 …api.error(core-api)에 둔다. 값도 뜻도 같고, DAG에서 놓일 수 있는 자리는 하나다.
mongodb-migration-flamingock은 Flamingock에 의존한다 검증하지 않은 외부 의존성을 더하는 것은 이 작업 범위 밖이었다. 설계도 공개 계약이 Flamingock 타입에 의존하지 않기를 요구한다 어댑터는 provider 중립이다. 플랫폼이 소유한 FlamingockChangeUnitView를 받는다. 실제 Flamingock 배포판을 잇는 일은 그 view 뒤의 파일 하나만 바꾸면 된다.
Testkit은 따로 된 Gradle 모듈 설계는 production 모듈이 testkit에 의존하는 것을 금한다 testkit은 testFixtures source set(ADR-BUILD-001)에 둔다. 컨테이너가 필요한 provider fixture는 별도 mongoProviderTestkit source set에 두어 보통 단위 테스트가 Testcontainers를 얻지 않게 한다. 방향은 MongoModuleBoundaryTest의 noProductionPackageDependsOnTheTestkit이 강제한다.
작업마다 git commit AGENTS.md: 커밋 정책은 human-only 구현은 stage하지 않은 채 넘겼고, 커밋은 사람이 했다. 계획 중 일부러 실행하지 않은 단계는 이것 하나이고, 여기 적어 둔다.
docs/mongodb/**, scripts/verify-mongodb-*.sh 저장소가 이미 docs/와 scripts/를 가진다 같은 저장소 상대 경로에 만들었다. 게이트 스크립트 둘은 지금도 있다(5절).

4. 설계에서 바뀌지 않은 것

  • D1 / D2 / D3 / D4 노출 plane과 순서가 정해진 D3 허가 절차(§5).
  • D1/D2 client 세대에는 apiStrict=true인 Stable API V1. D3/D4는 별도 세대.
  • 결과를 모르는 두 경우(WRITE_RESULT_UNKNOWN, TRANSACTION_COMMIT_UNKNOWN)를 포함한 MongoExecutionOutcome, 그리고 MongoFailureContext가 허락하는 필드 목록.
  • 안정된 예외 계층 전체와, 코드보다 label을 먼저 보는 분류 순서.
  • BSON 표현 manifest(UUID STANDARD, Decimal128, UTC 순간, 별칭 타입 metadata)와 문서 크기 예산.
  • update operator를 먼저 쓰는 쓰기, 그리고 문서 전체 교체의 선행 조건인 낙관적 revision.
  • 별개 loop인 transaction 본문 재시도와 commit 재시도: 본문 시도마다 새 session, commit 결과를 모르면 commit만 재시도. commit 결과를 모르면 본문을 다시 돌리지 않는다.
  • query, aggregation, index의 등록된 연산 이름과 manifest. 자유 형식 JSON query와 상한 없는 pipeline은 없다.
  • 인증한 cursor와 유일한 동률 처리 기준을 요구하는 keyset 페이지 나누기.
  • TTL은 물리적 정리일 뿐이다. 접근 거부나 업무 일정의 유일한 근거가 아니다.
  • manifest가 소유한 index/validator 상태와, 소유하지 않은 것은 절대 지우지 않는 적용 정책.
  • 가짓수가 적은 관측 tag, 명령 가리기, credential 참조 간접화.
  • Stable 릴리스 게이트의 증거 분류. Advanced 승격 요건(실제 토폴로지 증거)은 ADR-MONGO-ADV-001의 검토 의무다. 그것을 검사하는 클래스는 없다. scripts/verify-mongodb-advanced.sh는 빠진 증거를 보고할 뿐이다.

5. 검증

릴리스 게이트 스크립트 scripts/verify-mongodb-platform.sh와 scripts/verify-mongodb-advanced.sh가 있다. 이름을 지정한 Gradle lane을 돌리고, 건너뛴 lane을 통과로 세지 않으며, 승격 정보를 보고한다. 릴리스·승격 증거를 만들 때 쓴다. 아래 명령은 로컬 진단에 계속 쓸모가 있다.

src/에서:

./gradlew :adapter:outbound:persistence-mongo:check --console=plain
./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew :app-bootstrap:architectureTest --console=plain

컨테이너가 필요한 lane(mongoCompatibilityTest, mongoMigrationTest, mongoSecurityIntegrationTest, mongoReplicaSetTest, mongoFailoverTest, mongoPerformanceTest)은 check에 들어 있지 않다. MONGODB_DOCKER=1 bash scripts/verify-mongodb-platform.sh로 돌리거나, 이름으로 하나씩 돌린다.