donghyeon.kang/llm-wiki

Fork 0

Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

8.6 KiB

Raw Blame History

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title

source_type

url

archive_url

related_branches

related_projects

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 콜백 시그니처 확인 필요).

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

8.6 KiB Raw Blame History