문제: 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 문서의 파일 존재만 본다.
85 lines
4.6 KiB
Markdown
85 lines
4.6 KiB
Markdown
# 문서 모델링 가이드
|
|
|
|
설계서 §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를 `Binary` subtype 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](bson-mapping-guide.md) §5를 본다.
|
|
|
|
## 7. Collection profile
|
|
|
|
`MongoCollectionProfileRegistry`는 `CollectionProfileName`을 그 일관성 profile, 예산, 허용 목록에 묶는다.
|
|
등록하지 않은 collection에는 `MongoImperativeExecutor`로 닿을 수 없다. 허용 목록이 검토하지 않은
|
|
collection이 실수로 운영에 나타나는 것을 막는다.
|
|
|
|
## 8. 첫 insert 전에 적어 둘 것
|
|
|
|
1. 자식 collection마다 넣을지/가리킬지와 그 상한.
|
|
2. 크기 예산.
|
|
3. `_id` 표현.
|
|
4. Schema 버전 범위.
|
|
5. Index manifest([schema-index-migration-guide.md](schema-index-migration-guide.md)).
|
|
6. 일관성 profile([consistency-transaction-guide.md](consistency-transaction-guide.md)).
|
|
|
|
모두 지금은 싸고, 나중에는 마이그레이션이다.
|