Files
clean-architecture-backend-…/docs/jpa/transaction-guide.md
T
DongHyeonka b1cda0307b docs(jpa): JPA 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: `docs/jpa`의 문서 12개가 영어였고 `security.md`도 영어 절이 남아 있었다.
`repository-adaptation.md`는 Spring Boot 버전과 leaf 개수를 복사했다(number 예외).
번역하며 대조하니 지금 코드와 다른 주장이 여럿 있었다.

고친 것:
- 13개를 번역했다. 코드·명령·경로·표 구조는 그대로다. `support-matrix.md`의 DB 표와
  gate 표는 `JpaReleaseRendering`이 읽는 모양(`| PostgreSQL 17 | Stable |`,
  `` | `osiv-disabled` | gate | ``)을 그대로 둔다. 절 번호(§1~§5)는 코드가 인용해 그대로다.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Who may change the schema", "Bound the
  lock wait", "Concurrent index builds", "An invalid index exists", "Associations")은
  한국어 제목 뒤 괄호에 영어를 남겼다.
- 코드에 맞춘 주장:
  - support-matrix: 없는 `JpaPlatformAutoConfiguration.capabilities()` →
    `JpaPlatformReport.platformCapabilities()`. COPY 수준은 보고대로 Advanced.
  - repository-adaptation: leaf 개수·Boot 버전 → registry와 `libs.versions.toml`,
    `src/testkit` → `src/testFixtures`, outbox relay `app-bootstrap` →
    `composition:outbox-relay`, 「build-logic이 없다」 → `src/build-logic` convention
    plugin, 없는 `runtime_memberships`, 없는 `JpaDataSourceSettings`, 여러 major 선택은
    `JpaPlatformContractSupport.start()`가 거부한다(`StablePostgreSqlMatrixContractTest`만
    여러 개를 받는다), 이미지는 `container-images.properties`의 digest.
  - experimental-promotion-checklist: 결과 이름은 지운 gate의 것임을 밝혔다.
- 테스트: `JpaDocumentationContractTest`가 H2 단락의 「운영 보장이 아니」·「PostgreSQL 계약
  증거」와 「알려진 빈틈」을 본다. `PoolLaneClaimTest`는 한국어 금지 문구 셋을 더 본다.
  고친 두 테스트의 영어 `@DisplayName`은 AGENTS.md 규칙대로 한국어로 바꿨다.
- 예외 목록에서 JPA language 줄 12개와 number 줄 2개를 지웠다.

버린 대안: H2 단락의 영어 문구를 괄호로 남겨 단언을 그대로 두기. 독자가 읽는 것은
한국어 문장이므로 단언도 그 문장을 붙잡아야 한다.

위험·한계: `PoolLaneClaimTest`의 한국어 금지 문구는 지금 문서를 기준으로 고른 것이라,
다른 말로 쓴 인증 주장은 잡지 못한다. 영어 문구 검사는 그대로 남아 있다.

검증: 최종 트리 기준(첫 커밋 본문 참고).

검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:persistence-jpa:check` rc=0(666개 실패 0. `JpaDocumentationContractTest` 4,
  `JpaReleaseRenderingTest` 13, `PoolLaneClaimTest` 3), `:mainCheck` rc=0, `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `JpaDocumentationContractTest`의 H2 단락·알려진 빈틈 2개가 실패한다.
  `PoolLaneClaimTest`는 금지 문구를 더한 것이라 옛 영어 문서에서도 통과한다(RED 없음).
2026-11-07 17:56:34 +09:00

4.0 KiB

트랜잭션 가이드

설계서 §15-§20. 무엇이 트랜잭션을 가지고, 무엇을 다시 시도해도 되고, 무엇은 절대 안 되나.

경계는 애플리케이션 서비스가 가진다

repository 어댑터는 트랜잭션을 열지 않는다. use case가 TransactionPort로 연다. 작업 단위는 업무 결정이고, 그것이 어디서 시작하고 끝나는지는 use case만 알기 때문이다. 구현은 SpringTransaction 하나다. Spring의 PlatformTransactionManager 위에 mode마다 미리 만든 TransactionTemplate 하나를 두고, 모든 mode가 READ_COMMITTED로 돌며 시간 상한이 있다.

  • 격리 수준은 트랜잭션마다가 아니라 풀에 고정한다. module defaults가 spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED를 두고, HikariPoolConstraintValidator가 다른 수준을 거부한다. 수준을 이름 대는 template은 begin마다 pgjdbc가 서버에 그것을 묻게 한다(SHOW TRANSACTION ISOLATION LEVEL).
  • 시간 상한: app.persistence-jpa.transaction.write-timeout(inWrite, inRootWrite)과 read-timeout(inRead), 기본값은 각각 30 s다. inNew는 30 s로 고정이다. Spring이 남은 시간을 문장마다 넘기므로 서버가 느린 문장이나 잠금 대기를 취소하고 (DB_QUERY_CANCELED) 연결은 풀로 돌아간다. 더 오래 걸려야 하는 작업 단위는 보통 상한을 올릴 이유가 아니라 나눠야 할 batch 작업이다.
호출 전파 언제
inWrite REQUIRED, 읽기-쓰기 command 기본
inRootWrite REQUIRED, 읽기-쓰기, 돌기 전에 바깥 트랜잭션을 거부 물리 커밋을 증명해야 하는 조율
inRead REQUIRED, 읽기 전용 query 기본
inNew REQUIRES_NEW, 읽기-쓰기 혼자 커밋해야 하는 outbox / 감사 / 보상

Open Session In View는 모든 런타임 profile에서 꺼져 있다. Spring Boot에서는 기본으로 켜져 있어서, 설정 리뷰를 믿지 않고 JpaDangerousConfigurationGuard가 기동을 실패시킨다.

REQUIRES_NEW는 첫 물리 연결을 쥔 채 두 번째를 잡으므로 풀은 다음을 채워야 한다.

maximumPoolSize >= (concurrent_threads x (1 + max_requires_new_depth)) + 1

port는 아무것도 다시 시도하지 않는다

SpringTransaction은 action을 한 번 돌린다. 실패하면 롤백하고 넘기며, SQLSTATE를 알면 공유 영속성 오류 코드로 바꾼다. 잃은 @Version 경주는 SQLSTATE가 없고 DB_OPTIMISTIC_CONFLICT(409)로 보고한다. 다시 시도하기로 한 호출자는 문장 하나를 다시 보내지 말고 use case 전체를 새 트랜잭션에서 다시 돌린다. 낙관적 충돌이나 직렬화 실패는 시도가 기준으로 계산한 상태가 더는 커밋된 상태가 아니라는 뜻이기 때문이다.

이력: 이름 있는 정책, 마감 예산, 트랜잭션 로컬 시간 상한, 자동 전체 트랜잭션 재시도를 가진 두 번째 엔진 (SpringJpaTransactionExecutor, FullTransactionRetryCoordinator, PolicyTransactionPort)이 이것 옆에 있다가 2026-09-25에 지워졌다. 마지막 커밋은 docs/capability-status.md에 있다.

완료를 모름

커밋이 진행 중일 때 연결이 끊길 수 있다. 서버는 커밋했고 확인 응답만 잃었을 수 있다. TransactionCompletionUnknownException은 절대 다시 시도하지 않고, 타입 체계가 그것을 강제한다. JpaFailureContext는 다시 시도할 수 있는 완료 모름 실패를 표현하기를 거부한다. port 자신은 아무것도 다시 시도하지 않으므로, 그런 커밋은 호출자에게 실패로 정확히 한 번 나타난다 (PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried).

복구는 재시도가 아니라 맞추기다.

check the idempotency record -> check the business row -> check the outbox
                             -> still undetermined? escalate