解决Camunda将自定义RuntimeException转为UnexpectedRollbackException问题

问题根源 #

当被Camunda调用的方法抛出RuntimeException时，默认事务传播行为（REQUIRED）会将Camunda的主事务标记为rollback-only。Camunda在事务结束后检查到回滚状态，但未捕获到预期的自定义异常，就会抛出UnexpectedRollbackException覆盖你的原始异常信息。

具体解决方法 #

1. 调整事务传播行为 #

给被调用方法设置独立事务，避免影响Camunda主事务：

@Transactional(propagation = Propagation.REQUIRES_NEW)
public void sendPayment() {
    // 业务逻辑
    if (paymentFailureCondition) {
        throw new CustomRuntimeException("支付失败：账户余额不足");
    }
}

• 原理：REQUIRES_NEW会开启新的独立事务，方法抛出异常只会回滚自身事务，不会标记Camunda主事务为rollback-only，自定义异常能正常传递到流程中。

2. 使用受检异常并配置Camunda错误映射 #

将自定义异常改为受检异常，在流程中绑定错误事件：

// 自定义受检异常
public class CustomPaymentException extends Exception {
    public CustomPaymentException(String message) {
        super(message);
    }
}

// 被调用方法声明抛出异常
@Transactional
public void sendPayment() throws CustomPaymentException {
    if (paymentFailureCondition) {
        throw new CustomPaymentException("支付失败：订单已超时");
    }
}

• 在Camunda模型中，给send Payment服务任务添加错误边界事件，在事件配置中映射CustomPaymentException，并设置需要展示的自定义错误信息。

3. 手动管理事务 #

通过Spring事务管理器手动控制事务生命周期，确保自定义异常被正确抛出：

@Autowired
private PlatformTransactionManager transactionManager;

public void sendPayment() {
    TransactionStatus status = transactionManager.getTransaction(new DefaultTransactionDefinition());
    try {
        // 业务逻辑执行
        if (paymentFailureCondition) {
            throw new CustomRuntimeException("支付失败：网关连接超时");
        }
        transactionManager.commit(status);
    } catch (CustomRuntimeException e) {
        transactionManager.rollback(status);
        throw e; // 直接抛出自定义异常
    } catch (Exception e) {
        transactionManager.rollback(status);
        throw new CustomRuntimeException("支付处理异常", e);
    }
}

• 此方法绕过Camunda的事务代理，完全手动控制事务的提交/回滚，确保自定义异常不被覆盖。

4. 配置Camunda事务拦截器 #

通过自定义事务拦截器，让指定异常穿透事务检查：

@Configuration
public class CamundaTransactionConfig {
    @Bean
    public TransactionInterceptor camundaTransactionInterceptor(PlatformTransactionManager transactionManager) {
        Properties txAttrs = new Properties();
        // 配置sendPayment方法的事务属性，-CustomRuntimeException表示该异常不触发事务回滚标记
        txAttrs.setProperty("sendPayment", "PROPAGATION_REQUIRED,-CustomRuntimeException");
        return new TransactionInterceptor(transactionManager, txAttrs);
    }
}

• 原理：通过事务属性配置，让Camunda的事务拦截器遇到你的自定义RuntimeException时，不将事务标记为rollback-only，从而避免触发UnexpectedRollbackException。

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