4. 编程式事务：TransactionTemplate、PlatformTransactionManager、手动控制边界

在 Spring 生态中，声明式事务（@Transactional）虽然简洁，但在 Development 环境下调试 Kafka 消息链路时，往往需要更精细的事务边界控制。编程式事务允许开发者在代码中显式地开启、提交或回滚事务，尤其适合以下场景：

• 单个方法内需要执行多个独立的事务操作。
• 需要根据复杂的业务逻辑（如消息消费结果）动态决定事务的提交或回滚。
• 在 Kafka 消息监听器中，需要将数据库操作与消息偏移量提交绑定在同一个事务中。

4.1 核心 API 概览

Spring 提供了两套编程式事务管理方案，开发者可根据项目架构选择：

4.2 TransactionTemplate：声明式与编程式的桥梁

TransactionTemplate 通过回调机制，将事务边界与业务逻辑分离。开发者只需关注 TransactionCallback 或 TransactionCallbackWithoutResult 中的核心逻辑。

@Service
public class OrderService {

    private final TransactionTemplate transactionTemplate;
    private final JdbcTemplate jdbcTemplate;
    private final KafkaTemplate<String, String> kafkaTemplate;

    public OrderService(PlatformTransactionManager transactionManager,
                        JdbcTemplate jdbcTemplate,
                        KafkaTemplate<String, String> kafkaTemplate) {
        this.transactionTemplate = new TransactionTemplate(transactionManager);
        // 可选：设置事务属性，如隔离级别、超时时间
        this.transactionTemplate.setIsolationLevel(TransactionDefinition.ISOLATION_READ_COMMITTED);
        this.transactionTemplate.setTimeout(30);
        this.jdbcTemplate = jdbcTemplate;
        this.kafkaTemplate = kafkaTemplate;
    }

    public void createOrderWithEvent(Order order) {
        // 编程式事务边界
        transactionTemplate.execute(status -> {
            try {
                // 1. 数据库操作
                jdbcTemplate.update("INSERT INTO orders (id, product, amount) VALUES (?, ?, ?)",
                        order.getId(), order.getProduct(), order.getAmount());

                // 2. Kafka 消息发送（事务性）
                kafkaTemplate.send("order-events", order.getId(), order.toJson());

                // 3. 正常返回，自动提交事务
                return null;
            } catch (Exception e) {
                // 设置回滚
                status.setRollbackOnly();
                throw new RuntimeException("事务回滚，原因：" + e.getMessage(), e);
            }
        });
    }
}

4.3 PlatformTransactionManager：完全手动控制

当需要更细粒度的控制（如在一个事务中执行多个独立子事务，或使用保存点进行部分回滚）时，可以直接使用 PlatformTransactionManager。

@Service
public class PaymentService {

    private final PlatformTransactionManager transactionManager;
    private final JdbcTemplate jdbcTemplate;

    private static final TransactionDefinition TX_DEF = new DefaultTransactionDefinition(
            TransactionDefinition.PROPAGATION_REQUIRED);

    public PaymentService(PlatformTransactionManager transactionManager, JdbcTemplate jdbcTemplate) {
        this.transactionManager = transactionManager;
        this.jdbcTemplate = jdbcTemplate;
    }

    public void processPayment(String paymentId, String accountId, double amount) {
        TransactionStatus status = transactionManager.getTransaction(TX_DEF);
        try {
            // 业务操作
            jdbcTemplate.update("UPDATE accounts SET balance = balance - ? WHERE id = ?", amount, accountId);
            jdbcTemplate.update("INSERT INTO payments (id, account_id, amount) VALUES (?, ?, ?)",
                    paymentId, accountId, amount);

            // 手动提交
            transactionManager.commit(status);
        } catch (Exception e) {
            // 手动回滚
            transactionManager.rollback(status);
            throw new RuntimeException("支付事务回滚", e);
        }
    }
}

4.4 事务边界与 Kafka 消息链路：SVG 流程

下图展示了在 Kafka 消息消费过程中，使用编程式事务将“数据库写入”与“Kafka 偏移量提交”绑定为同一个原子操作的典型流程：

4.5 两种方案的对比与选择

4.6 开发环境调试技巧

• 日志增强： 在 application.yml 中开启事务日志：logging.level.org.springframework.transaction=DEBUG，可清晰看到事务的开启、提交、回滚日志。
• 断点位置： 在 transactionTemplate.execute() 的回调入口和 PlatformTransactionManager.commit() / rollback() 处设置断点，观察 TransactionStatus 的 isRollbackOnly() 和 isCompleted() 状态变化。
• 模拟回滚： 在回调中主动抛出 RuntimeException，验证数据库是否回滚、Kafka 消息是否未发送（事务性生产者模式下）。
• 边界测试： 使用 TransactionTemplate 的 setTimeout() 方法设置较短超时（如 3 秒），模拟数据库死锁或 Kafka 超时场景，观察事务的自动回滚行为。