Files
clean-architecture-backend-…/docs/mongodb/consistency-transaction-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

7.1 KiB

일관성과 transaction 가이드

설계서 §12–§16, 결정 D-07에서 D-10까지. 플랫폼에서 기본값을 잘못 고르면 가장 비싸고, 테스트에서는 가장 안 보이는 곳이다. 여기의 실패 모드는 모두 primary가 바뀌어야 재현되기 때문이다.

1. 문서 하나의 atomic 연산을 먼저 쓴다

D-09: transaction은 여러 문서에 걸친 불변식에만 쓴다. MongoDB에서 문서 하나는 이미 atomic이다. 문서 하나를 바꾸는 update를 transaction으로 감싸면 얻는 것은 없고, session 하나, two-phase commit, 결과를 모르는 새 경우 하나가 든다.

D-07: 일부만 바꿀 때는 save()가 아니라 update operator를 쓴다. MongoAtomicOperations / MongoAtomicOperationsTemplate은 MongoUpdateOperator로 operator($set, $inc, $push, $pull, $addToSet, $min, $max, $currentDate, …)를 내놓고, AtomicFilter 선행 조건과 ReturnDocumentMode를 받는다. save()로 읽고-고치고-쓰면 문서 전체를 바꾼다. 그 사이에 다른 쓰기가 바꾼 필드는 조용히 사라진다. 오류 없는 lost update다.

2. 문서 전체를 바꾸려면 revision이 필요하다

D-08. VersionedMongoUpdater는 MongoRevision을 요구한다. Spring Data @Version 필드이거나, VersionedUpdateCommand 안의 명시적인 기대 revision 조건이다. 교체 filter에 걸린 문서가 0개여도 「할 일 없음」이 아니다. MongoOptimisticConflictTranslator가 둘을 구분한다.

  • filter에 걸린 것이 없고 그 id가 없다 → MongoDocumentNotFoundException
  • filter에 걸린 것이 없고 그 id가 있다 → MongoOptimisticConflictException

이 둘을 하나로 합치면 동시 덮어쓰기가 404가 된다.

3. 일관성 profile

MongoConsistencyProfile은 read/write concern 쌍에 이름을 붙인다. MongoConsistencyRegistry가 profile을 연산이나 collection에 묶고, MongoConsistencyBinder가 실행할 때 적용한다.

Profile 뜻 쓰는 곳
PRIMARY_LOCAL primary 읽기, local concern rollback 구간을 견디는, 처리량이 중요한 읽기.
PRIMARY_MAJORITY primary 읽기, majority 쓰기 사용자가 곧바로 다시 볼 모든 것의 기본값.
CAUSAL_MAJORITY causal session 안의 majority 따로 떨어진 연산 사이에서 자기가 쓴 것을 읽기.
STALE_READ_ALLOWED secondary 읽기 허용 얼마나 낡았는지 밝히는 보고·분석.
SNAPSHOT_TRANSACTION snapshot 격리 transaction 안의 여러 문서 읽기.

profile은 힌트가 아니라 선언이다. registry는 연산마다 조회되고, profile을 등록하지 않은 연산은 기본값으로 가지 않고 거부된다.

4. Causal session

MongoCausalSessionContext와 SpringMongoCausalSessionExecutor가 연산 사이에 cluster time과 operation time을 옮긴다. 그래서 「쓰고 나서 읽기」가 다른 노드로 가도 쓴 값을 돌려받는다. causal session이 없으면 PRIMARY_MAJORITY는 내구성은 주지만, 호출 두 번에 걸쳐 자기가 쓴 것을 읽는 것은 보장하지 않는다.

5. Transaction

MongoTransactionExecutor는 session factory로 session을 열고, 본문을 돌리고, commit한다. MongoTransactionProfile은 일관성 profile, maxCommitTime, 재시도 예산을 가진다. 토폴로지가 중요하다. transaction에는 replica set이 필요하다. MongoStartupValidator는 STANDALONE에서 transaction을 선언한 profile을 첫 호출이 아니라 시작할 때 거부한다.

6. 재시도: 본문과 commit은 다른 loop다

D-10이고, 설계에서 결과가 가장 큰 규칙이다.

for each body attempt:
    open a NEW session
    run the body
        TransientTransactionError  -> abort, next body attempt
    commit
        UnknownTransactionCommitResult -> retry COMMIT ONLY, same session

MongoTransactionRetryCoordinator가 정확히 이것을 구현한다.

  • 본문 시도마다 새 session. abort한 뒤 session을 다시 쓰면 abort한 transaction의 상태가 재시도로 넘어간다.
  • commit 결과를 모르면 본문을 다시 돌리지 않는다. commit 결과를 모른다는 것은 commit이 이미 적용됐을 수 있다는 뜻이다. 본문을 다시 돌리면 두 번 적용된다. commit만 재시도하고, 이미 commit된 transaction에 대한 commit 재시도는 설계상 아무 일도 하지 않는다.
  • 예산이 두 loop를 모두 제한한다. MongoRetryBudget은 시도 횟수 와 흐른 시간을 제한하고, 흔들림을 준 backoff(delayBefore(attempt, random))를 쓴다. 힘든 primary를 재시도로 짓누르지 않는다.

MongoRetryDecision과 MongoRetryScope(…api.error에 있다)가 무엇을 재시도해도 되는지 말한다: MongoRetryScope.BODY, COMMIT_ONLY, NONE.

7. 결과를 모르는 경우

MongoExecutionOutcome의 값은 여섯이고, 그중 둘은 결과를 모르는 경우라 합치면 안 된다.

결과 쓰기가 일어났나?
NOT_SENT 아니다. 재시도해도 안전하다.
NO_WRITE_PERFORMED 아니다. 서버가 답했고 아무것도 하지 않았다.
WRITE_CONFIRMED 그렇다.
PARTIAL_BULK_WRITE 일부만. MongoBulkResult를 본다.
WRITE_RESULT_UNKNOWN 모른다.
TRANSACTION_COMMIT_UNKNOWN 모른다.

결과를 모르는 것은 실패가 아니고, 호출자에게 실패로 알리면 안 된다. 호출자는 맞춰 보거나 (MongoCommitReconciler가 본문이 쓴 결정적 표시를 다시 읽는다) 모른다는 사실을 그대로 위로 올린다. runbooks/unknown-commit.md를 본다.

MongoFailureContext는 설계가 허락한 필드만 남긴다: 결과, 분류, 연산 이름, collection profile, 재시도 범위, 시도 번호. query, 문서, 값은 남기지 않는다.

8. 실패 변환

DefaultMongoFailureClassifier는 코드보다 label을 먼저 본다. 서버의 error label (TransientTransactionError, UnknownTransactionCommitResult, RetryableWriteError)이 재시도 가능 여부에 대한 권위 있는 답이다. error code는 서버 버전마다 뜻이 바뀌는 보조 신호다. DefaultMongoFailureTranslator가 분류를 안정된 예외 계층에 대응시킨다. 맞는 것이 없으면 driver 타입을 흘리지 않고 MongoUnclassifiedFailureException이 된다.

9. Bulk 쓰기

MongoBulkExecutor는 항목별 MongoBulkItemFailure를 담은 MongoBulkResult를 돌려준다. 순서 없는 bulk 쓰기가 일부 실패하면 실패가 아니라 PARTIAL_BULK_WRITE다. 일부 문서는 쓰였다. 결과의 항목별 결과가 어느 index가 성공하고 어느 것이 실패했는지 말해 주므로, 호출자는 처음부터 다시 하지 않고 이어서 할 수 있다.

execute(context, documentType, plan)은 문서 하나 경로와 같이 모든 filter와 update를 document type에 맞춰 변환한다. 그래서 @Field 이름과 등록한 converter(DomainDocumentId, BigInteger)가 batch에서도 같은 뜻이다. 명령의 바이트 상한은 무엇이든 보내기 전에 그렇게 변환한 문서로 잰다.