Files
clean-architecture-backend-…/docs/mongodb/document-modeling-guide.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

4.3 KiB

Document Modeling Guide

Design §7–§9. The platform does not own your documents — D-01 is explicit that the domain owns @Document, repositories, queries, index requirements and schema version. What the platform owns is the set of modeling decisions that are expensive to reverse once a collection holds production data.

1. There is no CommonMongoRepository

A generic CommonMongoRepository<T, ID> is listed under explicitly unsupported (§3.4), and the reason is not purity. A shared supertype forces every collection to share an id strategy, a consistency profile and a query surface, and the first collection that needs a different one either gets a cast or a leaky generic parameter. Declare a Spring Data repository per aggregate.

2. Embed or reference

MongoDocumentModelManifest records the decision per collection so it is reviewable, and MongoDocumentModelValidator refuses the combinations that do not survive growth.

Descriptor Use when
EmbeddedCollectionDescriptor The child is read with the parent, is bounded, and has no independent lifecycle. Declare maxElements; an unbounded array is the single most common way a document reaches the size limit.
MongoReferenceDescriptor The child is queried independently, is unbounded, or outlives the parent. Declare MongoReferenceLifecycle so the deletion story is written down rather than discovered.

The validator rejects an embedded collection without a bound, and a reference whose lifecycle says the child is owned by the parent but which is also referenced from elsewhere.

3. Size budget

MongoDocumentSizeBudget:

Constant Bytes Meaning
MONGODB_HARD_LIMIT_BYTES 16 MiB MongoDB's own limit.
PLATFORM_CEILING_BYTES 4 MiB The largest budget the platform will accept.
DEFAULT_BYTES 2 MiB MongoDocumentSizeBudget.standard().

A budget above the ceiling is refused at construction. Budgeting to 16 MiB means the failing write is the first symptom, and by then the collection is already full of near-limit documents.

4. Identity

DomainDocumentId is written to _id as a BSON string by DomainIdWriteConverter. Any other representation is the document class's own field type. Pick the representation once per collection:

  • OBJECT_ID — server-generated, monotonic, 12 bytes. Good default when the domain has no natural id.
  • UUID_BINARY — a domain UUID stored as Binary subtype 4 (STANDARD). Never store a UUID as a string "because it is easier to read"; it doubles the index size and loses the type.
  • STRING — a natural key that is genuinely a string (a slug, an external system's id).

An _id choice is effectively permanent: it is the shard key candidate, the resume-token join key and the pagination tie-breaker.

5. Schema version

Every long-lived collection carries DocumentSchemaVersion. MongoSchemaVersionPolicy and MongoSchemaVersionRange say which versions the running code can read; a document outside the range raises MongoDataSchemaUnsupportedException rather than being silently mapped with missing fields.

Write the range down before the migration, not after: the range is what lets old and new instances run at once during a rolling deploy.

6. Type metadata

@LongLivedMongoDocument marks a document whose stored type alias must not be a Java class name. MongoTypeMetadataRegistry maps alias → class. Storing the FQCN means moving or renaming the class becomes a data migration; storing an alias keeps it a refactor. See bson-mapping-guide.md §4.

7. Collection profiles

MongoCollectionProfileRegistry binds a CollectionProfileName to its consistency profile, budget and allowlist. A collection that is not registered cannot be reached through MongoImperativeExecutor — the allowlist is the mechanism that keeps an unreviewed collection from appearing in production by accident.

8. What to write down before the first insert

  1. Embed/reference decision per child collection, with bounds.
  2. Size budget.
  3. _id representation.
  4. Schema version range.
  5. Index manifest (see schema-index-migration-guide.md).
  6. Consistency profile (see consistency-transaction-guide.md).

Each of these is cheap now and a migration later.