Files
clean-architecture-backend-…/docs/mongodb/document-modeling-guide.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

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)).
모두 지금은 싸고, 나중에는 마이그레이션이다.