Files
clean-architecture-backend-…/docs/mongodb/bson-mapping-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

90 lines
5.0 KiB
Markdown

# BSON 매핑 가이드
설계서 §10과 결정 D-06. 값이 BSON에서 어떤 모양으로 저장되는지는 구현 세부가 아니라 데이터 계약이다.
collection에 문서가 백만 개 쌓인 뒤 `BigDecimal` 저장 방식을 바꾸면 코드 수정이 아니라 중단 시간이 드는
마이그레이션이다. `MongoTypeRepresentationManifest`가 표현을 고정해서 라이브러리 업그레이드나 다른
기본값이 그것을 바꾸지 못하게 한다.
## 1. Manifest
`MongoTypeRepresentationManifest.standard()`가 정하는 것:
| Java 타입 | BSON | 표현 타입 |
|---|---|---|
| `UUID` | `Binary` subtype 4 | `MongoUuidRepresentation.STANDARD` |
| `BigDecimal` | `Decimal128` | `MongoDecimalRepresentation.DECIMAL_128` |
| `BigInteger` | `Decimal128`(범위를 넘으면 선언한 경우 `String`) | `MongoBigIntegerRepresentation` |
| `Instant` / `OffsetDateTime` / `ZonedDateTime` | UTC `Date` | `MongoTemporalRepresentation.UTC_DATE` |
| `LocalDate` | `String`(ISO-8601) 또는 UTC `Date`, 필드마다 선언 | `MongoTemporalRepresentation` |
| `enum` | `String` 이름 | `MongoEnumRepresentation.NAME` |
`MongoMappingConfiguration`과 `MongoCustomConversionsFactory`가 이 manifest로 Spring Data converter를
만든다. 그래서 읽을 곳도 한 곳, 바꿀 곳도 한 곳이다.
## 2. UUID
늘 `UuidRepresentation.STANDARD`(subtype 4)다. driver의 옛 Java 표현(subtype 3)은 UUID의 두 절반의
바이트 순서를 뒤집는다. 그래서 한 표현으로 쓴 문서를 다른 표현으로 읽으면 다르면서도 멀쩡해 보이는
UUID가 나온다. 오류는 나지 않고 엉뚱한 행을 얻는다. 같은 이유로 golden snapshot kit은 codec을
명시적으로 고정한다(`MongoBsonSnapshot.defaultRegistry()`).
## 3. Decimal
`BigDecimal` → `Decimal128`이다. `Double`은 쓰지 않는다. `12.30`을 double로 저장하면
`12.299999999999999`가 된다. 그 값으로 쓴 금액 비교는 언젠가 1원 틀리고, 그것을 알아채는 고객이 있다.
`BigDecimalToDecimal128Converter` / `Decimal128ToBigDecimalConverter`는 manifest에서 등록한다.
`Decimal128`의 유효 숫자는 34자리다. 그 범위를 넘는 `BigDecimal`은 조용히 반올림하지 않고 쓸 때 실패한다.
## 4. 시간
지역 시각이 아니라 순간(instant)을 저장한다. `LocalDateTimeMappingGuard`는 매핑된 문서의
`LocalDateTime` 필드를 거부한다. `LocalDateTime`에는 offset이 없다. 그래서 저장되는 값이 그 값을 쓴
인스턴스의 JVM 기본 시간대에 따라 달라지고, rolling 배포 중인 두 인스턴스의 값이 어긋날 수 있다.
순간이 중요하면 `Instant`를, 달력의 날짜가 중요하면 `LocalDate`를 쓴다.
## 5. 타입 metadata
`MongoTypeMetadataPolicy`가 `_class`에 무엇을 넣을지 정한다.
| 정책 | 저장하는 것 | 쓰는 때 |
|---|---|---|
| `NONE` | 없음 | collection에 타입이 정확히 하나이고 앞으로도 하위 타입이 들어오지 않는다. |
| `ALIAS` | 등록한 짧은 별칭 | 오래 사는 collection의 다형 계층. |
| `CLASS_NAME` | FQCN | 짧게 사는 collection이나 내부 collection에만. |
`PolicyAwareMongoTypeMapper`가 이 정책을 강제하고, `MongoTypeMetadataRegistry`가 별칭 → 클래스를
가진다. `@LongLivedMongoDocument` 타입에 `CLASS_NAME`을 쓰면 거부한다. 문서 백만 개에
`com.example.OrderV2`를 써 두면 package 이름을 바꾸는 일이 데이터 마이그레이션이 된다.
## 6. 없음과 null
golden kit은 이 둘을 일부러 구분한다. `MongoBsonSnapshotAssert.hasNoField(...)`와
`hasExplicitNull(...)`은 다른 단언이다. MongoDB에서 둘은 다른 문서이기 때문이다.
`{"a": null}`은 `{a: null}`과 `{a: {$exists: true}}`에 모두 걸리지만 `{}`는 앞의 것에만 걸린다.
mapper가 바뀌어 null을 명시적으로 쓰기 시작하면 query 결과가 조용히 달라진다.
## 7. Golden 표현 테스트
표현이 고정된 collection에는 snapshot 테스트를 둔다.
```java
MongoBsonSnapshot snapshot = MongoBsonSnapshot.of(storedDocument);
MongoBsonSnapshotAssert.assertThat(snapshot)
.hasBsonType("amount", "DECIMAL128")
.hasBsonType("externalId", "BINARY")
.hasNoJavaClassName("dev.caskeleton")
.hasTypeSignature("_id:OBJECT_ID,amount:DECIMAL128,createdAt:DATE_TIME,externalId:BINARY");
```
`hasTypeSignature`가 회귀 게이트다. 값이 같은지만 보는 단언이 통과시킬 변화까지 포함해 *어떤* 표현
변화에도 실패한다. 실패하면 물을 것은 문자열을 고칠지가 아니라, 그 변화가 의도한 것이고 마이그레이션이
있는지다.
## 8. 왕복
`MongoRoundTripContract`는 두 가지를 단언한다. `write → read`가 같은 도메인 객체를 돌려준다. *그리고*
`write → read → write`가 똑같은 BSON 문서를 만든다. 뒤의 것이 비대칭 converter를 잡는다. 읽으면 같지만
다시 직렬화하면 달라지는 값은 이후의 모든 `save()`를 쓸데없는 update로 만들고, change stream을 잡음
발생기로 만든다.