문제: 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 문서의 파일 존재만 본다.
90 lines
5.0 KiB
Markdown
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을 잡음
|
|
발생기로 만든다.
|