llm-wiki/raw/official-docs/transaction-template-spring-official.md

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

title	source_type	url	archive_url	status	confidence	tags	related_projects	related_branches	created	last_reviewed
Programmatic Transaction Management :: Spring Framework Reference	official-doc	https://docs.spring.io/spring-framework/reference/data-access/transaction/programmatic.html		raw	high	ca-transaction-boundary transaction-template spring-official programmatic-tx transaction-management	ca-skeleton-operational-contract	feature-application-port-usecase-contract feature-transaction-concurrency-contract	2026-05-22	2026-05-27

Programmatic Transaction Management :: Spring Framework Reference

Layer: raw/official-docs/ — Spring Framework 7.x reference, data-access/transaction/programmatic 섹션 verbatim 발췌. ca-tmpl TransactionPort adapter 의 내부 구현 후보 (TransactionTemplate.execute(...)) 의 1차 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-application-port-usecase-contract	TransactionPort adapter 가 내부적으로 TransactionTemplate 을 사용하는 구현 선택의 공식 근거 (Spring 권장 programmatic 패턴)
raw/branch-notes/feature-transaction-concurrency-contract	Topic 2 — Transaction Boundary 대안 2 (TransactionTemplate programmatic) 의 공식 정의·콜백 시맨틱·imperative vs reactive 권장 비교 baseline

컨텍스트

ca-tmpl 의 TransactionPort 결정에 대한 대안 2: TransactionTemplate 명시적 호출. Spring 이 공식적으로 권장하는 programmatic 패턴이며, port adapter 내부 구현으로 종종 채택됨.

출처 / Source

• 원본 URL: https://docs.spring.io/spring-framework/reference/data-access/transaction/programmatic.html
• 아카이브 URL: (미수집)
• 저자 / 조직: Spring Framework / VMware (Broadcom)
• 발행일: Spring Framework 7.x reference (current, rolling docs)
• 마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§Using the TransactionTemplate] "The TransactionTemplate adopts the same approach as other Spring templates, such as the JdbcTemplate. It uses a callback approach (to free application code from having to do the boilerplate acquisition and release transactional resources) and results in code that is intention driven, in that your code focuses solely on what you want to do."

[§Programmatic Transaction Management] "The Spring team generally recommends the TransactionTemplate for programmatic transaction management in imperative flows and TransactionalOperator for reactive code."

[§Using the TransactionTemplate] "Application code that must run in a transactional context and that explicitly uses the TransactionTemplate resembles the next example. You, as an application developer, can write a TransactionCallback implementation (typically expressed as an anonymous inner class) that contains the code that you need to run in the context of a transaction. You can then pass an instance of your custom TransactionCallback to the execute(..) method exposed on the TransactionTemplate."

[§Using the TransactionTemplate] "Code within the callback can roll the transaction back by calling the setRollbackOnly() method on the supplied TransactionStatus object, as follows:"

return transactionTemplate.execute(new TransactionCallback() {
    public Object doInTransaction(TransactionStatus status) {
        updateOperation1();
        return resultOfUpdateOperation2();
    }
});

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
TX-TMPL-C1	TransactionTemplate 은 JdbcTemplate 등 다른 Spring template 와 동일한 callback 접근법 — 트랜잭션 리소스 획득/해제 boilerplate 를 application code 에서 제거하여 intention-driven 코드를 가능하게 함	[§Using the TransactionTemplate] "The TransactionTemplate adopts the same approach as other Spring templates... It uses a callback approach (to free application code from having to do the boilerplate acquisition and release transactional resources) and results in code that is intention driven..."	official-vendor-doc	Spring TransactionTemplate 사용 시	callback 접근법이 declarative @Transactional 보다 더 권장된다는 뜻은 아님 — 둘 다 공식 옵션
TX-TMPL-C2	Spring 팀의 programmatic transaction management 공식 권장: imperative flow 에는 TransactionTemplate, reactive code 에는 TransactionalOperator	[§Programmatic Transaction Management] "The Spring team generally recommends the TransactionTemplate for programmatic transaction management in imperative flows and TransactionalOperator for reactive code."	official-vendor-doc	programmatic transaction management 가 필요한 경우	programmatic 이 declarative 보다 우월하다는 뜻은 아님 — 두 패러다임의 권장 도구 선택만 명시
TX-TMPL-C3	사용 패턴: 개발자가 TransactionCallback 구현 (보통 anonymous inner class) 을 작성하고, TransactionTemplate.execute(..) 메서드에 전달	[§Using the TransactionTemplate] "...you can write a TransactionCallback implementation (typically expressed as an anonymous inner class) that contains the code that you need to run in the context of a transaction. You can then pass an instance of your custom TransactionCallback to the execute(..) method..."	official-vendor-doc	TransactionTemplate.execute() 호출 시	Java 8+ lambda 가 동일하게 동작한다는 뜻을 본 인용으로 직접 보장할 수는 없음 (별도 확인 필요 — 실무에선 가능)
TX-TMPL-C4	callback 내부에서 TransactionStatus.setRollbackOnly() 호출로 명시적 rollback 가능	[§Using the TransactionTemplate] "Code within the callback can roll the transaction back by calling the setRollbackOnly() method on the supplied TransactionStatus object..."	official-vendor-doc	TransactionTemplate.execute() 콜백 내부	exception throwing 으로도 rollback 가능한지는 본 인용 범위 밖 (RuntimeException 으로 rollback 되는 declarative 시맨틱과의 매핑은 별도)

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • TX-TMPL-C1 ~ C4: Spring 공식의 TransactionTemplate callback 패턴, imperative/reactive 권장 도구 분리, 사용 시그니처, 명시적 rollback 메커니즘
• 이 자료가 증명하지 않는 것:
  • TransactionTemplate 을 application service 에서 직접 사용하는 것이 clean architecture 와 양립 가능하다는 평가 (여전히 org.springframework.transaction.support.TransactionTemplate import 발생 — architecture-level 판단은 ca-tmpl 측 결정)
  • TransactionTemplate 이 @Transactional 보다 성능상 우월/열등하다는 비교 (본 페이지는 성능 비교 미포함)
  • exception throwing 시 자동 rollback 시맨틱 (RuntimeException 의 기본 rollback rule 등 — 별도 페이지)
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • ca-tmpl 의 TransactionPort adapter 가 TransactionTemplate.execute() 를 호출할 때 lambda 사용 가능 여부 (실무 통례지만 본 인용은 anonymous inner class 만 예시)
  • setRollbackOnly() 와 exception 기반 rollback 의 우선순위 / 충돌 처리

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

• 적용 시나리오: 메서드 단위가 아니라 메서드 내부 일부 블록만 트랜잭션으로 묶고 싶을 때. 또는 reactive 가 아니지만 declarative AOP 를 피하고 싶을 때.
• 장점:
  • 트랜잭션 경계가 코드에 명시적으로 보임. AOP proxy 우회 / self-invocation 같은 함정 없음.
  • 한 메서드 안에서 트랜잭션 블록과 비트랜잭션 블록을 자유롭게 섞을 수 있음.
  • reactive: TransactionalOperator 사용 (TX-TMPL-C2).
• 단점:
  • application service 가 직접 사용하면 여전히 org.springframework.transaction.support.TransactionTemplate import 발생 → clean architecture 위반은 동일.
  • 모든 트랜잭션 블록마다 callback boilerplate 발생.
• ca-tmpl (TransactionPort) 와의 차이: TransactionTemplate 은 구현 디테일이고, ca-tmpl 은 그것을 한 단계 더 감싼 port 를 둠. 즉 TransactionPort 의 adapter 가 내부적으로 TransactionTemplate.execute(...) 를 호출하는 형태가 자연스러움.
• testability 영향: 중간 — port 없이 직접 쓰면 여전히 Spring 의존 테스트 필요. port 로 감싸면 ↑.
• code 복잡도 영향: 중간 — 콜백 noise.

Related / 관련

• 같은 주제 다른 official-doc:
  • raw/official-docs/at-transactional-spring-official (대안 1: declarative @Transactional)
• 적용 ca-tmpl branch-note:
  • raw/branch-notes/feature-application-port-usecase-contract
  • raw/branch-notes/feature-transaction-concurrency-contract
• canonical contract 섹션:
  • raw/project-notes/ca-skeleton-operational-contract (§14. Transaction / Concurrency Contract, §5. Exception Ownership Contract)
• 대안 그룹: Topic 2 — Transaction Boundary (5종: TransactionPort / @Transactional direct / TransactionTemplate / Functional monad / Custom AOP) — 본 source 는 대안 2.
• 인용한 wiki 요약: (미작성)