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

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