llm-wiki/raw/official-docs/spring-tx-management-reference.md

title, source_type, url, archive_url, related_projects, related_branches, tags, status, confidence, created, last_reviewed

title	source_type	url	archive_url	related_projects	related_branches	tags	status	confidence	created	last_reviewed
Spring Framework — Transaction Management (@Transactional, PlatformTransactionManager, Propagation)	official-doc	https://docs.spring.io/spring-framework/reference/data-access/transaction.html			feature-repository-access-permission-contract feature-transaction-concurrency-contract feature-application-port-usecase-contract	spring-framework spring-tx transaction declarative-tx propagation isolation rollback aop-proxy platform-transaction-manager official-doc	raw	high	2026-05-27	2026-05-27

Spring Framework — Transaction Management (@Transactional, PlatformTransactionManager, Propagation)

Layer: raw/official-docs/ — Spring Framework Reference / "Transaction Management" 챕터 verbatim. Repository / Service 계층의 @Transactional 위치, propagation 선택, rollback 규칙, AOP self-invocation 함정의 1차 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-repository-access-permission-contract	D4 — Repository 메서드 직접 호출과 UseCase 경유의 트랜잭션 경계 차이. AOP proxy self-invocation 으로 @Transactional 이 우회될 수 있다는 사실을 근거로 "UseCase 만 @Transactional 보유" 규칙 채택
raw/branch-notes/feature-transaction-concurrency-contract	@Transactional 의 default propagation REQUIRED / rollback 정책 / isolation 옵션의 공식 정의
raw/branch-notes/feature-application-port-usecase-contract	UseCase (application port impl) 가 트랜잭션 경계 owner 라는 설계 결정의 공식 근거 — PlatformTransactionManager 는 SPI 이고 @Transactional 은 외부 호출에서만 발동

컨텍스트

ca-tmpl 계열 프로젝트의 Clean Architecture 레이어링에서 트랜잭션 경계는 UseCase (application layer) 에 둔다. 이 결정의 정당화는 다음 두 가지 공식 사실에 기반: (1) Spring 의 @Transactional 은 default 로 AOP proxy 기반이라 self-invocation 시 발동하지 않음, (2) propagation REQUIRED 가 default 이므로 UseCase 진입 후 호출되는 모든 Repository 메서드는 동일 트랜잭션을 공유. 본 자료는 두 사실을 verbatim 으로 보존하기 위한 raw.

출처 / Source

• 원본 URL: https://docs.spring.io/spring-framework/reference/data-access/transaction.html
• 보조 URL (sub-pages):
  • https://docs.spring.io/spring-framework/reference/data-access/transaction/strategies.html (PlatformTransactionManager / TransactionDefinition / TransactionStatus)
  • https://docs.spring.io/spring-framework/reference/data-access/transaction/declarative/annotations.html (@Transactional 속성 / proxy mode / rollback rules)
• 아카이브 URL: (미수집)
• 저자 / 조직: Spring Framework (VMware / Broadcom)
• 발행일: rolling docs (current = 6.x)
• 마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§Transaction Management - Introduction] "Comprehensive transaction support is among the most compelling reasons to use the Spring Framework."

[§Transaction Management - Introduction] "A consistent programming model across different transaction APIs, such as Java Transaction API (JTA), JDBC, Hibernate, and the Java Persistence API (JPA)."

[§Understanding the Spring Framework Transaction Abstraction] "The key to the Spring transaction abstraction is the notion of a transaction strategy. A transaction strategy is defined by a TransactionManager, specifically the org.springframework.transaction.PlatformTransactionManager interface for imperative transaction management and the org.springframework.transaction.ReactiveTransactionManager interface for reactive transaction management."

[§Understanding the Spring Framework Transaction Abstraction - PlatformTransactionManager API] "This is primarily a service provider interface (SPI), although you can use it programmatically from your application code. Because PlatformTransactionManager is an interface, it can be easily mocked or stubbed as necessary."

[§TransactionStatus Interface] "The TransactionStatus interface provides a simple way for transactional code to control transaction execution and query transaction status. The concepts should be familiar, as they are common to all transaction APIs."

[§@Transactional Settings - Propagation] "The propagation setting is PROPAGATION_REQUIRED."

[§@Transactional Settings - Rollback Default] "Any RuntimeException or Error triggers rollback, and any checked Exception does not."

[§@Transactional Settings - Rollback Attributes] "rollbackFor: Array of Class objects, which must be derived from Throwable. Optional array of exception types that must cause rollback."

[§In proxy mode - Self-Invocation] "In proxy mode (which is the default), only external method calls coming in through the proxy are intercepted. This means that self-invocation (in effect, a method within the target object calling another method of the target object) does not lead to an actual transaction at runtime even if the invoked method is marked with @Transactional."

[§@Transactional Settings - Isolation] "isolation: enum: Isolation - Optional isolation level. Applies only to propagation values of REQUIRED or REQUIRES_NEW."

[§@Transactional Settings - ReadOnly] "readOnly: boolean - Read-write versus read-only transaction. Only applicable to values of REQUIRED or REQUIRES_NEW."

[§@Transactional Settings - Timeout] "timeout: int (in seconds of granularity) - Optional transaction timeout. Applies only to propagation values of REQUIRED or REQUIRES_NEW."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SPRING-TX-MGR-C1	Spring 의 transaction abstraction 은 JTA / JDBC / Hibernate / JPA 등 서로 다른 transaction API 위에 일관된 프로그래밍 모델을 제공한다	[§Transaction Management - Introduction] "A consistent programming model across different transaction APIs, such as Java Transaction API (JTA), JDBC, Hibernate, and the Java Persistence API (JPA)."	official-vendor-doc	Spring Framework 6.x	특정 ORM 별 미세한 동작 차이(예: JPA flush 시점)는 본 인용 범위 밖
SPRING-TX-MGR-C2	transaction strategy 는 PlatformTransactionManager interface (imperative) 또는 ReactiveTransactionManager (reactive) 로 정의된다. 이는 SPI 로, application code 에서 직접 사용도 가능하며 mock/stub 이 쉽다	[§Understanding the Spring Framework Transaction Abstraction] "The key to the Spring transaction abstraction is the notion of a transaction strategy. A transaction strategy is defined by a TransactionManager, specifically the org.springframework.transaction.PlatformTransactionManager interface..." + [§PlatformTransactionManager API] "This is primarily a service provider interface (SPI)... PlatformTransactionManager is an interface, it can be easily mocked or stubbed as necessary."	official-vendor-doc	Spring Framework 6.x, imperative/reactive 모두	구체적 구현체(DataSourceTransactionManager, JpaTransactionManager 등) 의 동작 차이는 본 인용 범위 밖
SPRING-TX-MGR-C3	@Transactional 의 default propagation 은 PROPAGATION_REQUIRED 다	[§@Transactional Settings - Propagation] "The propagation setting is PROPAGATION_REQUIRED."	official-vendor-doc	@Transactional annotation 사용 시 (속성 미지정)	REQUIRES_NEW / NESTED / SUPPORTS 등 다른 propagation 의 정확한 시맨틱은 별도 페이지 참조 필요
SPRING-TX-MGR-C4	@Transactional 의 default rollback rule 은 "RuntimeException 또는 Error 면 rollback, checked Exception 은 rollback 하지 않음" 이다. rollbackFor / noRollbackFor 속성으로 override 가능	[§@Transactional Settings - Rollback Default] "Any RuntimeException or Error triggers rollback, and any checked Exception does not." + [§Rollback Attributes] "rollbackFor: Array of Class objects, which must be derived from Throwable. Optional array of exception types that must cause rollback."	official-vendor-doc	@Transactional 속성 미지정 (default)	XML 기반 <tx:advice> 설정의 default 가 동일한지는 본 인용 범위 밖
SPRING-TX-MGR-C5	proxy mode 가 default 이고, proxy 를 거치지 않는 self-invocation (같은 target object 내부의 다른 메서드 호출) 은 @Transactional 이 붙어 있어도 실제 transaction 을 발동시키지 않는다	[§In proxy mode - Self-Invocation] "In proxy mode (which is the default), only external method calls coming in through the proxy are intercepted. This means that self-invocation (in effect, a method within the target object calling another method of the target object) does not lead to an actual transaction at runtime even if the invoked method is marked with @Transactional."	official-vendor-doc	Spring AOP proxy mode (default), @EnableTransactionManagement(mode = PROXY)	AspectJ mode (mode = ASPECTJ) 에서도 동일하게 우회된다는 뜻은 아님 — AspectJ 모드는 self-invocation 도 가로챔
SPRING-TX-MGR-C6	@Transactional 의 isolation, readOnly, timeout 속성은 propagation 값이 REQUIRED 또는 REQUIRES_NEW 일 때만 적용된다	[§@Transactional Settings - Isolation] "isolation: ... Applies only to propagation values of REQUIRED or REQUIRES_NEW." + [§ReadOnly] "readOnly: ... Only applicable to values of REQUIRED or REQUIRES_NEW." + [§Timeout] "timeout: ... Applies only to propagation values of REQUIRED or REQUIRES_NEW."	official-vendor-doc	@Transactional annotation, propagation REQUIRED / REQUIRES_NEW	SUPPORTS / NOT_SUPPORTED / NESTED 등에서 isolation/readOnly/timeout 가 적용되는지는 본 인용 범위 밖 (적용 안 됨 시사)

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • SPRING-TX-MGR-C1: Spring 이 JTA/JDBC/Hibernate/JPA 위에 통합 프로그래밍 모델 제공
  • SPRING-TX-MGR-C2: PlatformTransactionManager 는 SPI; imperative 와 reactive 가 분리된 interface
  • SPRING-TX-MGR-C3: @Transactional default propagation = REQUIRED
  • SPRING-TX-MGR-C4: default rollback = unchecked exception 만 (checked 는 안 함); rollbackFor 로 override
  • SPRING-TX-MGR-C5: proxy mode (default) 에서 self-invocation 은 @Transactional 우회
  • SPRING-TX-MGR-C6: isolation/readOnly/timeout 은 REQUIRED/REQUIRES_NEW 한정
• 이 자료가 증명하지 않는 것:
  • 특정 DB (PostgreSQL, MySQL, Oracle) 별 isolation level 의 실제 잠금 동작
  • JPA persistence context 의 flush/clear 시점이 @Transactional 경계와 정확히 어떻게 맞물리는지
  • @Transactional 이 메서드 visibility (private, protected) 와 어떻게 상호작용하는지 — 별도 페이지에서 "public only" 명시
  • "Repository 에 @Transactional 을 두면 안 된다" 는 베스트 프랙티스 — 본 페이지는 위치를 규정하지 않음
  • propagation REQUIRES_NEW 가 별도 connection 을 사용하는지, 같은 connection 의 savepoint 인지의 정확한 동작
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • ca-tmpl 의 UseCase 가 같은 클래스 안의 다른 UseCase 메서드를 호출하면 @Transactional 이 우회되는지 — SPRING-TX-MGR-C5 에 따라 우회됨, 별도 bean 분리 또는 self-injection 패턴 필요
  • JPA EntityManager.flush() 가 application port impl 의 어느 시점에서 호출되는지 검증 (commit 시점 default)
  • Repository (jOOQ / JPA) 메서드 직접 호출 시 트랜잭션 없이 동작하는지 — @Transactional 미존재 시 auto-commit 동작 검증

메모 / Notes

• 인용 1 해석 후보 (미검증):
  • SPRING-TX-MGR-C5 (self-invocation 우회) → ca-tmpl 의 "UseCase = port impl 1:1" 원칙은 이 함정을 자연 회피
• 추가로 봐야 할 동일 출처 페이지:
  • https://docs.spring.io/spring-framework/reference/data-access/transaction/declarative/tx-propagation.html (propagation 시맨틱 상세)
  • https://docs.spring.io/spring-framework/reference/data-access/transaction/declarative/aspectj.html (AspectJ mode 차이)

Related / 관련

• 같은 주제 다른 official-doc:
  • raw/official-docs/spring-smartlifecycle-reference
  • raw/official-docs/spring-restclient-builder-reference
• 인용하는 branch:
  • raw/branch-notes/feature-repository-access-permission-contract
  • raw/branch-notes/feature-transaction-concurrency-contract
  • raw/branch-notes/feature-application-port-usecase-contract
• 인용하는 project:
  • raw/project-notes/ca-skeleton-operational-contract
• 인용하는 wiki: (미작성)