llm-wiki/raw/official-docs/spring-transaction-synchronization-manager-javadoc.md

---
title: "official-doc / Spring Framework — TransactionSynchronizationManager Javadoc"
source_type: official-doc
url: https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/transaction/support/TransactionSynchronizationManager.html
archive_url:
related_branches: [feature-application-port-usecase-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, persistence, spring-framework, transaction-synchronization, domain-event, tenant-isolation]
created: 2026-05-28
---

# official-doc / Spring Framework — TransactionSynchronizationManager Javadoc

> Layer: `raw/` — 외부 자료(공식 문서)의 원문 발췌·출처 기록.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-application-port-usecase-contract]] | ca-tmpl `application-core`의 Spring annotation 직접 import 금지 원칙 하에서, domain event의 commit-bound publish를 `@TransactionalEventListener` 없이 구현할 수 있는 공식 SPI로 `TransactionSynchronizationManager.registerSynchronization()`을 채택. 또한 모든 자원 바인딩이 per-thread 보장됨을 근거로 multi-tenant 호환성 정당화. |

## 출처 / Source

- 원본 URL: https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/transaction/support/TransactionSynchronizationManager.html
- 아카이브 URL: (미등록 — 추후 archive.org 스냅샷 등록 권장)
- 저자 / 조직: Juergen Hoeller / Spring Framework (VMware / Broadcom)
- 발행일: Since 02.06.2003 (Spring Framework 공식 Javadoc, current 버전)
- 마지막 확인일: 2026-05-28

## 왜 저장했는지 / Why archived

ca-tmpl의 `application-core`는 Spring 어노테이션을 직접 import하지 않는다. 트랜잭션 커밋 후 domain event를 publish하는 port 구현에서, `@TransactionalEventListener` 없이 커밋 바운드 동작을 달성하는 공식 SPI 근거가 필요하다. `TransactionSynchronizationManager.registerSynchronization()`이 그 공식 SPI이며, 동시에 per-thread 자원 격리 보장이 multi-tenant 환경에서의 안전성 근거가 된다.

## 핵심 인용 / Key quotes (verbatim)

> [§class-level javadoc, line 106-107] "Central delegate that manages resources and transaction synchronizations per thread.
> To be used by resource management code but not by typical application code."

> [§class-level javadoc, line 120-125] "Transaction synchronization must be activated and deactivated by a transaction
> manager via `initSynchronization()` and `clearSynchronization()`.
> This is automatically supported by `AbstractPlatformTransactionManager`,
> and thus by all standard Spring transaction managers, such as
> `JtaTransactionManager` and
> `DataSourceTransactionManager`."

> [§registerSynchronization method javadoc, line 544-545] "Register a new transaction synchronization for the current thread.
> Typically called by resource management code."

> [§class-level javadoc, line 113-114] "Resource management code should check for thread-bound resources, for example, JDBC
> Connections or Hibernate Sessions, via `getResource`."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| TSM-C1 | `TransactionSynchronizationManager`는 자원과 트랜잭션 동기화를 per-thread로 관리하며, 일반 애플리케이션 코드가 아닌 자원 관리 코드용 SPI이다. | [§class-level, line 106-107] "Central delegate that manages resources and transaction synchronizations per thread. To be used by resource management code but not by typical application code." | `official-reference` | Spring Framework를 사용하는 모든 자원 관리 코드 | application layer가 이 API를 직접 호출해도 된다는 뜻이 아님. 오히려 이 API는 port 구현체(infrastructure)가 사용해야 한다. |
| TSM-C2 | 트랜잭션 동기화는 `AbstractPlatformTransactionManager`(및 그 구현체인 `DataSourceTransactionManager`, `JtaTransactionManager` 등)에 의해 자동으로 활성화·비활성화된다. | [§class-level, line 120-125] "Transaction synchronization must be activated and deactivated by a transaction manager via initSynchronization() and clearSynchronization(). This is automatically supported by AbstractPlatformTransactionManager..." | `official-reference` | Spring 표준 트랜잭션 관리자를 사용하는 환경 | 커스텀 트랜잭션 관리자가 `AbstractPlatformTransactionManager`를 상속하지 않는 경우는 별도 확인 필요. |
| TSM-C3 | `registerSynchronization()`은 현재 스레드의 트랜잭션에 새 동기화 콜백을 등록하며, 자원 관리 코드가 호출하는 것이 전형적인 사용 패턴이다. | [§registerSynchronization, line 544-545] "Register a new transaction synchronization for the current thread. Typically called by resource management code." | `official-reference` | 트랜잭션이 활성화된 스레드 내에서 커밋/롤백 후 콜백이 필요한 모든 자원 관리 코드 | 트랜잭션 동기화가 비활성화된 상태(`isSynchronizationActive() == false`)에서의 동작은 보장되지 않음. `IllegalStateException` throw. |
| TSM-C4 | 모든 자원(JDBC Connection, Hibernate Session 등)은 per-thread로 바인딩되며, 자원 관리 코드는 `getResource()`를 통해 현재 스레드에 바인딩된 자원을 조회해야 한다. | [§class-level, line 113-114] "Resource management code should check for thread-bound resources, for example, JDBC Connections or Hibernate Sessions, via getResource." | `official-reference` | Spring 트랜잭션 컨텍스트에서 동작하는 모든 자원 관리 인프라 코드 | virtual thread(Project Loom) 환경에서의 ThreadLocal semantics 변화는 별도 검증 필요. |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `TSM-C1`: `TransactionSynchronizationManager`는 자원 관리 코드(= infrastructure/port 구현체)를 위한 SPI이며, application layer(use case)에서 직접 사용해서는 안 된다는 공식 설계 의도.
  - `TSM-C2`: Spring 표준 트랜잭션 관리자(`DataSourceTransactionManager` 등)를 사용하는 환경에서 동기화 활성화는 자동이다.
  - `TSM-C3`: commit-bound domain event publish를 위해 port 구현체가 `registerSynchronization()`을 호출하는 것은 공식 SPI의 전형적 사용 패턴이다.
  - `TSM-C4`: per-thread 자원 격리는 Spring 트랜잭션 관리의 기본 보장이며, multi-tenant 시나리오에서 스레드 간 자원 누출이 없음을 지지한다.
- 이 자료가 증명하지 않는 것:
  - `@TransactionalEventListener`보다 `registerSynchronization()`이 성능적으로 우수하다는 주장.
  - Virtual thread 또는 reactive(Project Reactor) 환경에서의 per-thread 보장 — ThreadLocal semantics가 다르므로 별도 공식 문서 확인 필요.
  - ca-tmpl의 특정 port 구현 코드가 실제로 이 SPI를 사용하고 있다는 사실 (`actually-implemented` 등급은 코드 확인 필요).
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-tmpl `application-core`에서 실제로 `TransactionSynchronizationManager`를 import하지 않고 port interface + infrastructure 구현체 분리가 되어 있는지 코드 레벨 확인.
  - `isSynchronizationActive()` 체크 없이 `registerSynchronization()`을 호출하는 경우 `IllegalStateException` 발생 — port 구현체에서 방어 로직 필요.

## 메모 / Notes

- `registerSynchronization()`을 호출하는 port 구현체는 `TransactionSynchronization` 인터페이스를 구현해야 하며, 이 인터페이스도 spring-tx 모듈에 속함. ca-tmpl의 application-core가 이 인터페이스를 직접 참조하는지, 아니면 별도 abstraction을 두는지는 branch-note에서 결정해야 할 사항.
- `bindSynchronizedResource()` (Spring 7.0 신규)는 트랜잭션 완료 후 자동 언바인딩을 지원하는 programmatic 방식. `registerSynchronization()`의 보완적 대안이나 Spring 7.0 이상에서만 사용 가능.
- 추가로 봐야 할 동일 출처 페이지: `TransactionSynchronization` 인터페이스 Javadoc (afterCommit, afterCompletion 콜백 시그니처 확인 필요).

## Related / 관련

- [[raw/official-docs/at-transactional-spring-official]] — `@Transactional` 공식 문서. `TransactionSynchronizationManager`와 함께 쓰일 때의 동작 이해에 보완.
- 이 자료를 인용한 wiki 요약: `wiki/concepts/transaction-synchronization` (생성 시)