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

121 lines
7.1 KiB
Markdown

# 일관성과 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](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에서도
같은 뜻이다. 명령의 바이트 상한은 무엇이든 보내기 전에 그렇게 변환한 문서로 잰다.