# 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을 잡음 발생기로 만든다.