문제: 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 문서의 파일 존재만 본다.
4.6 KiB
문서 모델링 가이드
설계서 §7–§9. 플랫폼은 여러분의 문서를 소유하지 않는다. D-01이 분명히 말한다: @Document, repository,
query, index 요구 사항, schema 버전은 도메인이 소유한다. 플랫폼이 소유하는 것은 collection에 운영
데이터가 쌓인 뒤에는 되돌리기 비싼 모델링 결정들이다.
1. CommonMongoRepository는 없다
범용 CommonMongoRepository<T, ID>는 명시적으로 지원하지 않는 목록(§3.4)에 있다. 이유는 순수성이 아니다.
공통 상위 타입은 모든 collection에 같은 id 전략, 같은 일관성 profile, 같은 query 면을 강요한다. 다른 것이
필요한 첫 collection은 cast를 하거나 새는 generic 인자를 얻는다. aggregate마다 Spring Data repository를
선언한다.
2. 넣을까, 가리킬까
MongoDocumentModelManifest가 collection마다 이 결정을 적어 검토할 수 있게 하고,
MongoDocumentModelValidator가 커지면 버티지 못하는 조합을 거부한다.
| Descriptor | 쓰는 때 |
|---|---|
EmbeddedCollectionDescriptor |
자식을 부모와 함께 읽고, 개수에 상한이 있고, 따로 사는 수명이 없다. maxElements를 선언한다. 상한 없는 배열이 문서가 크기 한도에 닿는 가장 흔한 길이다. |
MongoReferenceDescriptor |
자식을 따로 조회하거나, 개수에 상한이 없거나, 부모보다 오래 산다. MongoReferenceLifecycle을 선언해서 삭제 방식을 나중에 발견하지 않고 미리 적어 둔다. |
validator는 상한 없는 embedded collection을 거부한다. lifecycle이 「부모가 자식을 소유한다」고 하면서 다른 곳에서도 가리키는 reference도 거부한다.
3. 크기 예산
MongoDocumentSizeBudget:
| 상수 | 바이트 | 뜻 |
|---|---|---|
MONGODB_HARD_LIMIT_BYTES |
16 MiB | MongoDB 자체 한도. |
PLATFORM_CEILING_BYTES |
4 MiB | 플랫폼이 받아들이는 가장 큰 예산. |
DEFAULT_BYTES |
2 MiB | MongoDocumentSizeBudget.standard(). |
상한을 넘는 예산은 생성할 때 거부한다. 예산을 16 MiB로 잡으면 실패한 쓰기가 첫 증상이고, 그때는 이미 collection이 한도 가까운 문서로 가득하다.
4. 식별자
DomainIdWriteConverter가 DomainDocumentId를 _id에 BSON 문자열로 쓴다. 그 밖의 표현은 문서 클래스
자신의 필드 타입이 정한다. collection마다 표현을 한 번 고른다.
OBJECT_ID— 서버가 만들고, 단조 증가하며, 12바이트다. 도메인에 자연 id가 없을 때 좋은 기본값이다.UUID_BINARY— 도메인 UUID를Binarysubtype 4(STANDARD)로 저장한다. 「읽기 쉬워서」 UUID를 문자열로 저장하지 않는다. index 크기가 두 배가 되고 타입을 잃는다.STRING— 정말 문자열인 자연 key(slug, 외부 시스템의 id).
_id 선택은 사실상 영구적이다. shard key 후보이고, resume token의 join key이고, 페이지 나누기의 동률
처리 기준이다.
5. Schema 버전
오래 사는 collection은 모두 DocumentSchemaVersion을 가진다. MongoSchemaVersionPolicy와
MongoSchemaVersionRange가 실행 중인 코드가 읽을 수 있는 버전을 말한다. 범위 밖의 문서는 필드가 빠진
채 조용히 매핑되지 않고 MongoDataSchemaUnsupportedException을 던진다.
범위는 마이그레이션 뒤가 아니라 앞에 적는다. 범위가 있어야 rolling 배포 중에 옛 인스턴스와 새 인스턴스가 함께 돈다.
6. 타입 metadata
@LongLivedMongoDocument는 저장하는 타입 별칭이 Java 클래스 이름이면 안 되는 문서를 표시한다.
MongoTypeMetadataRegistry가 별칭 → 클래스를 대응시킨다. FQCN을 저장하면 클래스를 옮기거나 이름을 바꾸는
일이 데이터 마이그레이션이 된다. 별칭을 저장하면 리팩터링으로 남는다.
bson-mapping-guide.md §5를 본다.
7. Collection profile
MongoCollectionProfileRegistry는 CollectionProfileName을 그 일관성 profile, 예산, 허용 목록에 묶는다.
등록하지 않은 collection에는 MongoImperativeExecutor로 닿을 수 없다. 허용 목록이 검토하지 않은
collection이 실수로 운영에 나타나는 것을 막는다.
8. 첫 insert 전에 적어 둘 것
- 자식 collection마다 넣을지/가리킬지와 그 상한.
- 크기 예산.
_id표현.- Schema 버전 범위.
- Index manifest(schema-index-migration-guide.md).
- 일관성 profile(consistency-transaction-guide.md).
모두 지금은 싸고, 나중에는 마이그레이션이다.