在Quarkus 3.19（JTA）中获取PSQLException根因的方法

问题场景 #

使用Quarkus 3.19结合JTA时，通过@ServerExceptionMapper捕获事务异常，但当前处理器只能拿到RollbackException，无法获取导致回滚的原始PSQLException，而日志文件中存在该异常的完整栈信息。

当前异常处理器代码：

@ServerExceptionMapper
public RestResponse<ErrorMessage> handleRollbackException(QuarkusTransactionException exception) {
    Throwable cause = exception;
    while (cause.getCause() != null && cause.getCause() != cause) {
        cause = cause.getCause();
    }
    log.info(cause.getClass()
            .getName() + "\n" + cause.toString());
    var message = ErrorMessage.builder()
            .type("/service/transaction-exception")
            .title("Could not persist data")
            .status(Response.Status.CONFLICT)
            .detail(cause.getMessage())
            .instance(String.format("%s:%s", applicationName, cause.getMessage()))
            .build();
    return RestResponse.status(message.getStatus(), message);
}

当前日志输出：

INFO  requestId= processId= [co.nx.po.op.ws.er.QuarkusExceptionMappers] (vert.x-eventloop-thread-1) jakarta.transaction.RollbackException
jakarta.transaction.RollbackException: ARJUNA016053: Could not commit transaction.

解决方案与最佳实践 #

1. 调整事务管理器配置，暴露原始异常 #

Quarkus默认使用Narayana作为JTA事务管理器，默认会隐藏底层异常。添加以下配置到application.properties，让事务管理器暴露原始异常作为RollbackException的cause：

quarkus.narayana-jta.expose-cause=true

2. 改进异常链遍历逻辑，精准定位PSQLException #

当前遍历逻辑仅获取最底层的异常，但可能存在多层包装，且未针对性查找PSQLException。可以实现一个更健壮的异常查找方法：

private Throwable findRootPSQLException(Throwable exception) {
    Set<Throwable> processedExceptions = new HashSet<>();
    Throwable current = exception;
    
    while (current != null && !processedExceptions.contains(current)) {
        processedExceptions.add(current);
        // 直接匹配目标异常类型，找到即返回
        if (current instanceof PSQLException) {
            return current;
        }
        current = current.getCause();
    }
    // 未找到时返回最后遍历到的异常（兜底）
    return current != null ? current : exception;
}

在处理器中调用该方法：

@ServerExceptionMapper
public RestResponse<ErrorMessage> handleRollbackException(QuarkusTransactionException exception) {
    Throwable rootCause = findRootPSQLException(exception);
    // 建议打印完整栈轨迹，便于排查
    log.info("Root exception type: {}", rootCause.getClass().getName(), rootCause);
    
    var message = ErrorMessage.builder()
            .type("/service/transaction-exception")
            .title("Could not persist data")
            .status(Response.Status.CONFLICT)
            .detail(rootCause.getMessage())
            .instance(String.format("%s:%s", applicationName, rootCause.getMessage()))
            .build();
    return RestResponse.status(message.getStatus(), message);
}

3. 最佳实践总结 #

• 针对性异常匹配：优先查找目标异常类型（如PSQLException），而非仅依赖最底层异常，避免无关异常干扰
• 防止循环引用：使用Set记录已处理的异常，避免异常链循环导致死循环
• 配置暴露原始异常：开启Narayana的expose-cause配置是获取底层数据库异常的关键前提
• 完整日志记录：打印异常的完整栈轨迹（而非仅toString()），方便后续问题排查
• 客户端友好响应：根据原始异常的具体类型（如唯一键冲突、外键约束等），返回更精准的错误状态码和信息

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