문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만 지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다. 그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데, 2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다. - check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다· 입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드, 따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다. - runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가 울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다. - 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명, docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안). - docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고, 링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs docs-system.md 6.2절 다섯 칸)을 더했다. 버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다). 위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo 밖이라 고치지 않았다(총괄에게 알린다). 검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함), check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시 worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건, 1건 실패했다.
4.2 KiB
결정 기록 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-13
- 요약: BSON 표현을 고정한 목록으로 관리한다는 결정이다.
- 현재 정본:
docs/mongodb/bson-mapping-guide.md
ADR-MONGO-002 — BSON 표현은 고정한 manifest다
- 상태: 채택
- 날짜: 2026-08-13
- 설계 출처: 설계 §10, 결정 D-06
배경
Java 값을 BSON으로 어떻게 나타내는지는 데이터 계약인데, 기본 toolchain의 어떤 것도 그것을 계약으로 다루지 않는다. Spring Data와
MongoDB driver에는 둘 다 기본값이 있고, 그 기본값은 버전마다 바뀌어 왔다. BigDecimal은 Double, String, Decimal128 중
무엇으로든 들어갈 수 있다. UUID는 Binary subtype 3이나 subtype 4로 들어갈 수 있다. Instant는 Date나 String으로 들어갈
수 있다.
결과는 비대칭이다. 표현이 바뀌어도 값 동등 시험에는 보이지 않는다 — 12.30은 double이든 Decimal128이든 12.30처럼 보인다 —
하지만 collection에 운영 데이터가 들면 그것을 바꾸는 것은 전체 migration이다. 그리고 UUID 경우는 migration보다 나쁘다: 옛 Java
표현은 UUID의 두 절반을 byte-swap하므로, 한 표현으로 쓰고 다른 표현으로 읽은 문서는 다르지만 유효해 보이는 UUID를 낸다.
오류는 없다. 엉뚱한 레코드를 받는다.
결정
MongoTypeRepresentationManifest가 플랫폼이 대응시키는 모든 타입의 표현을 고정하고, MongoMappingConfiguration이 그것으로
Spring Data converter를 만든다. 라이브러리 기본값에 기대는 것은 없다.
| Java | BSON | 근거 |
|---|---|---|
UUID |
Binary subtype 4(STANDARD) |
subtype 3은 byte-swap한다. 표현을 넘나드는 읽기는 소리 없이 틀린다. |
BigDecimal |
Decimal128 |
double은 12.30을 나타내지 못한다. double로 비교한 돈은 결국 1원씩 틀린다. |
BigInteger |
Decimal128, 범위를 넘으면 선언한 String |
유효 숫자 34자리. 범위를 넘으면 반올림하지 않고 쓰기에서 실패한다. |
Instant / OffsetDateTime / ZonedDateTime |
UTC Date |
시각 하나, 표현 하나. |
LocalDate |
필드마다 선언 | 달력의 날은 시각이 아니다. |
LocalDateTime |
거절 | offset이 없다: 저장 값이 쓰는 JVM의 기본 시간대에 따라 달라진다. |
enum |
String 이름 |
누가 상수를 끼워 넣으면 ordinal이 다시 매겨진다. |
타입 metadata는 MongoTypeMetadataPolicy — NONE, ALIAS, CLASS_NAME — 를 따른다. @LongLivedMongoDocument 타입은
CLASS_NAME을 쓰면 안 된다: 문서 백만 개에 FQCN을 쓰면 패키지 이름 바꾸기가 데이터 migration이 된다.
manifest는 golden gate가 강제한다. MongoBsonSnapshot이 저장된 문서를 정규화하면서 BSON 타입을 지키고 없음과 null을 구별해
두며, MongoBsonSnapshotAssert.hasTypeSignature(...)가 표현이 바뀌면 실패한다. registry는 기본값을 물려받지 않고
UuidCodec(STANDARD)를 명시해 고정한다. 기본값을 물려받는 것이 바로 gate가 잡으려는 어긋남이기 때문이다.
결과
좋은 점. 라이브러리 업그레이드가 시험을 실패시키지 않고 표현을 옮길 수 없다. 돈이 정확하다. UUID가 자기 자신으로 다시 읽힌다. 클래스 옮기기는 리팩터링으로 남는다.
나쁜 점. 표현에 영향을 주는 모든 변경에 snapshot 갱신 그리고 migration 작성이 필요하다. 새로 대응시키는 타입은 쓰기 전에 manifest 항목이 필요하다. 의도한 마찰이다: 대안은 운영에서 변경을 발견하는 것이다.
버린 대안 — 「JSON을 snapshot한다」. JSON은 gate가 지키는 바로 그 구별을 없앤다: Decimal128과 String은 둘 다 글로
나오고, Binary UUID와 ObjectId는 둘 다 hex로 나오며, 없음과 null은 둘 다 사라진다.