Mastering Spring Transaction Hooks for Safe Kafka Publishing

Spring developers often need to publish domain events, such as payment logs, to Kafka while ensuring that the publishing does not interfere with the primary transaction of the business service. This guide walks through a real‑world payment‑system scenario, proposes a reusable second‑party library, and demonstrates how to leverage Spring's transaction hook mechanisms.

Case Background

A payment system must record every account's fund flow. To prevent fraud, the CTO requires an archival subsystem that receives fund‑flow messages via Kafka and writes them to a dedicated database with write‑only permission. The overall flow is:

Because multiple business units will need similar archiving, the CTO suggests building a second‑party library whose sole responsibility is to send messages to Kafka.

Solution Design

The library must satisfy four constraints:

1. It should be a Spring Boot starter. 2. It must create its own Kafka producer instead of using Spring's KafkaTemplate to avoid conflicts with existing integrations. 3. It should expose a simple API that is easy to adopt. 4. Message sending must support transactions and not block the main business logic.

The critical requirement is #4: the library must detect whether a transaction is active and, if so, defer the Kafka send until after the transaction commits.

TransactionSynchronizationManager in Action

The following pseudo‑code implements the required behavior using TransactionSynchronizationManager and an internal single‑thread executor.

private final ExecutorService executor = Executors.newSingleThreadExecutor();

public void sendLog() {
    // Check if a transaction is active
    if (!TransactionSynchronizationManager.isSynchronizationActive()) {
        // No transaction – send immediately in async thread
        executor.submit(() -> {
            try {
                // send to Kafka
            } catch (Exception e) {
                // log or alert
            }
        });
        return;
    }

    // Transaction is active – register a synchronization callback
    TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronizationAdapter() {
        @Override
        public void afterCompletion(int status) {
            if (status == TransactionSynchronization.STATUS_COMMITTED) {
                // After commit, send asynchronously
                executor.submit(() -> {
                    try {
                        // send to Kafka
                    } catch (Exception e) {
                        // log or alert
                    }
                });
            }
        }
    });
}

Detecting Transaction Presence

The static method TransactionSynchronizationManager.isSynchronizationActive() returns true when the thread‑local synchronizations set has been populated by Spring's transaction manager at the start of a transaction. Internally, the manager calls initSynchronization(), which creates a new LinkedHashSet in a ThreadLocal variable.

Registering a Synchronization Callback

When a transaction is active, the library registers a TransactionSynchronizationAdapter via registerSynchronization(). The adapter overrides afterCompletion(int status), which Spring invokes after the transaction finishes. By checking that status == TransactionSynchronization.STATUS_COMMITTED, the library ensures the Kafka message is sent only after a successful commit, while a rollback results in no send.

Spring executes registered synchronizations during the invokeAfterCommit and invokeAfterCompletion phases, allowing custom logic to run at the appropriate moment.

Conclusion

The solution demonstrates how to safely integrate asynchronous Kafka publishing into a Spring transaction without impacting the primary business flow. Key take‑aways are:

Use TransactionSynchronizationManager.isSynchronizationActive() to detect an ongoing transaction.

Register a TransactionSynchronizationAdapter to execute code after commit.

Perform the actual Kafka send in a separate thread to keep the main transaction lightweight.

Avoid thread switching inside the callback; otherwise the thread‑local transaction flag may be lost and the hook will not fire.

By encapsulating this logic in a reusable starter, multiple services can share a consistent, conflict‑free way to archive critical data to Kafka.