문제: 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 문서의 파일 존재만 본다.
121 lines
7.1 KiB
Markdown
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에서도
|
|
같은 뜻이다. 명령의 바이트 상한은 무엇이든 보내기 전에 그렇게 변환한 문서로 잰다.
|