Quarkus Reactive Panache：非REST端点用@ReactiveTransactional遇事务异常

问题根源分析 #

批量处理时出现Transaction already completed、Session is currently connecting to database这类异常，核心原因是每条消息的事务上下文未做到完全隔离，或是异步操作的订阅逻辑错误，导致事务被提前关闭、复用，甚至出现会话资源冲突。Reactive事务依赖上下文的传播机制，批量场景下若未确保单条消息处理链绑定独立事务上下文，就会触发这类问题。

正确用法与修复方案 #

1. 让每条消息的处理链绑定独立事务上下文 #

不要在批量遍历的外层调用带@ReactiveTransactional的方法，要确保单条消息的业务逻辑完全在独立事务上下文内执行。如果是基于列表的批量处理，建议将列表转为Multi流，通过flatMap触发事务方法（map不会订阅内部的Uni，无法正确初始化事务上下文）。

示例代码调整：

// 消息接收服务
public class MessageReceiver {
    @Inject
    BusinessService businessService;

    public Uni<Void> processBatch(List<Message> messages) {
        // 转Multi流+flatMap确保每条消息的事务独立执行
        return Multi.fromIterable(messages)
                .flatMap(message -> businessService.doOperation(message))
                .collect().asList()
                .replaceWithVoid();
    }
}

// BusinessService保持@ReactiveTransactional绑定到单条消息处理方法
@ApplicationScoped
public class BusinessService {
    @Inject
    AppleRepo appleRepo;
    @Inject
    MelonRepo melonRepo;

    @ReactiveTransactional
    public Uni<Void> doOperation(Message message) {
        // 业务逻辑：基于Panache的Reactive持久化操作
        return appleRepo.persist(new Apple(message.getAppleData()))
                .chain(() -> melonRepo.persist(new Melon(message.getMelonData())))
                .replaceWithVoid();
    }
}

2. 避免事务上下文的意外传播或复用 #

• 不要在@ReactiveTransactional方法内手动管理会话、事务（比如调用EntityManager的事务API），Panache与Reactive事务管理器会自动处理资源生命周期。
• 如果是定时任务触发的批量处理（比如Quarkus的@Scheduled），确保定时方法返回Uni/Multi，内部事务逻辑通过flatMap触发，绝对不要用await().indefinitely()这类阻塞操作——阻塞会直接破坏Reactive事务的上下文管理机制。

3. 按需强制开启全新事务 #

默认事务传播属性是REQUIRED，如果批量处理的外层存在隐式事务，可显式指定传播属性为REQUIRES_NEW，强制每条消息开启完全独立的事务：

@ReactiveTransactional(propagation = TransactionPropagation.REQUIRES_NEW)
public Uni<Void> doOperation(Message message) {
    // ...业务逻辑
}

这个设置能彻底隔离每条消息的事务上下文，避免外层事务的干扰。

4. 规范PanacheRepositoryBase的使用 #

确保你的Repo是标准的Reactive实现，不要添加阻塞操作：

@ApplicationScoped
public class AppleRepo implements PanacheRepositoryBase<Apple, Long> {
    // 仅需继承，无需手动实现基础CRUD方法
}

所有持久化操作必须返回Uni/Multi，保证Reactive流的连续性，否则会打断事务上下文的传播。

关键注意事项 #

• Reactive事务完全依赖Reactive流的上下文传播，必须确保事务方法的返回值（Uni/Multi）被正确订阅，仅调用方法不订阅会导致事务无法触发，还可能引发资源泄漏。
• 批量处理时可通过flatMap的并发参数限制并发数（比如flatMap(message -> ..., 10)），避免瞬间耗尽数据库连接池，引发会话连接类异常。

内容的提问来源于stack exchange，提问作者Hzt