Quarkus Hibernate Reactive：onFailure()未捕获ConstraintViolationException

问题根源分析 #

1. 异常被多层包装：Hibernate Reactive的异步操作中，ConstraintViolationException通常会被包裹在CompletionException或其他RuntimeException里，直接捕获该类型无法命中。
2. 错误处理逻辑一刀切：你的createUser方法把所有异常都统一转为RegistrationFailedException，导致上层无法识别原始的唯一约束冲突异常。
3. 未针对性过滤异常：当前的onFailure()块没有指定捕获特定异常类型，无法区分邮箱重复和其他数据库错误场景。

修复方案 #

步骤1：修改createUser方法，精准识别唯一约束异常 #

调整异常处理逻辑，先解包真实异常，针对邮箱唯一约束场景抛出自定义UserAlreadyExistsException，其他异常保留原有处理：

public Uni<Auth> createUser(Auth authRequest) {
    User user = new User(authRequest);
    String passwordHash = Password.hash(authRequest.getPassword()).withArgon2().getResult();
    user.setPasswordHash(passwordHash);
    
    return PanacheEntityBase.persist(user)
            .onItem().transform(success -> {
                log.info("Successfully created user, email: {}", authRequest.getEmail());
                return authRequest;
            })
            .onFailure().invoke(ex -> {
                // 逐层解包获取真实异常
                Throwable rootCause = ex;
                while (rootCause.getCause() != null && !(rootCause instanceof ConstraintViolationException)) {
                    rootCause = rootCause.getCause();
                }
                
                // 判断是否为邮箱唯一约束冲突
                if (rootCause instanceof ConstraintViolationException) {
                    ConstraintViolationException cve = (ConstraintViolationException) rootCause;
                    if ("23505".equals(cve.getSQLException().getSQLState()) 
                        && cve.getMessage().contains("user_email_key")) {
                        throw new UserAlreadyExistsException("该邮箱已被注册");
                    }
                }
                // 其他异常抛原有自定义异常
                log.error("Unable to create User, email: {}, Exception: {}",
                        authRequest.getEmail(), ex.getMessage(), ex);
                throw new RegistrationFailedException(Errors.UNABLE_TO_REGISTER_USER + ex.getMessage());
            });
}

步骤2：上层接口区分处理自定义异常 #

在registerUser方法中，针对UserAlreadyExistsException返回符合REST规范的409 Conflict状态码，其他异常返回500：

@POST
@Path("/register")
@WithTransaction
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Uni<Response> registerUser(@Valid Auth authRequest) {
    return authService.createUser(authRequest)
            .onItem().transform(success -> Response.status(Response.Status.CREATED)
                    .entity(success).build())
            // 单独处理邮箱重复异常
            .onFailure(UserAlreadyExistsException.class)
            .recoverWithItem(ex -> {
                log.warn("User already exists, email: {}", authRequest.getEmail());
                ErrorResponse errorResponse = new ErrorResponse(ex.getMessage(), Response.Status.CONFLICT);
                return Response.status(Response.Status.CONFLICT).entity(errorResponse).build();
            })
            // 处理其他异常
            .onFailure()
            .recoverWithItem(ex -> {
                log.error("Unable to create User, email: {}, Exception: {}", authRequest.getEmail(), ex.getMessage(), ex);
                ErrorResponse errorResponse = new ErrorResponse(ex.getMessage(), Response.Status.INTERNAL_SERVER_ERROR);
                return Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(errorResponse).build();
            });
}

补充说明 #

• SQL状态码判断：PostgreSQL中唯一约束冲突的标准SQL状态码是23505，结合约束名user_email_key可以精准定位邮箱重复场景，避免误判其他唯一约束。
• 异常解包逻辑：异步操作的异常会被多层包装，通过循环获取根因能确保拿到真实的ConstraintViolationException。
• 状态码规范：邮箱重复属于客户端请求冲突，返回409 Conflict比500内部错误更符合REST接口设计规范。

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