문제: 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 문서의 파일 존재만 본다.
5.0 KiB
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 테스트를 둔다.
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을 잡음
발생기로 만든다.