Spring Boot项目中如何捕获Hibernate抛出的错误信息？

DevOps 小满

2026-10-2

需求可行性说明

该需求完全可以实现。Spring Boot 提供的全局异常处理机制支持捕获指定类型的运行时异常，Hibernate 抛出的所有持久化相关异常都属于可被拦截的运行时异常，你可以在现有通用错误捕获逻辑的基础上扩展即可。

具体实现步骤

第一步：确认全局异常处理器已配置
你需要先有使用@RestControllerAdvice（前后端分离项目）或@ControllerAdvice（带页面渲染项目）注解的全局异常处理类，这是Spring Boot统一异常捕获的核心组件。
第二步：新增Hibernate特定异常捕获方法
Hibernate 常见的可捕获异常类型如下：
- org.hibernate.exception.ConstraintViolationException：数据约束违反异常，触发场景包括唯一键冲突、非空字段未赋值、外键关联数据不存在等
- org.hibernate.ObjectNotFoundException：查询目标对象不存在
- org.hibernate.StaleObjectStateException：乐观锁冲突，触发场景为多并发更新同一条数据时版本号不匹配
- org.hibernate.QueryException：HQL/JPQL 语句语法错误
  你可以直接在全局异常处理类中添加对应异常的捕获方法，代码示例如下：

import org.hibernate.exception.ConstraintViolationException;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.util.HashMap;
import java.util.Map;

@RestControllerAdvice
public class GlobalExceptionHandler {
    // 你已经实现的通用异常捕获逻辑
    @ExceptionHandler(Exception.class)
    public ResponseEntity<Map<String, Object>> handleCommonException(Exception e) {
        Map<String, Object> result = new HashMap<>();
        result.put("code", 500);
        result.put("msg", "系统内部错误");
        return new ResponseEntity<>(result, HttpStatus.INTERNAL_SERVER_ERROR);
    }

    // 新增Hibernate约束违反异常捕获逻辑
    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<Map<String, Object>> handleConstraintViolation(ConstraintViolationException e) {
        Map<String, Object> result = new HashMap<>();
        result.put("code", 400);
        String errorMsg = String.format("数据操作失败：%s", e.getSQLException().getMessage());
        result.put("msg", errorMsg);
        return new ResponseEntity<>(result, HttpStatus.BAD_REQUEST);
    }

    // 新增Hibernate对象不存在异常捕获逻辑
    @ExceptionHandler(org.hibernate.ObjectNotFoundException.class)
    public ResponseEntity<Map<String, Object>> handleObjectNotFound(org.hibernate.ObjectNotFoundException e) {
        Map<String, Object> result = new HashMap<>();
        result.put("code", 404);
        result.put("msg", String.format("目标数据不存在：%s", e.getMessage()));
        return new ResponseEntity<>(result, HttpStatus.NOT_FOUND);
    }
}

第三步：处理被Spring包装的Hibernate异常
部分场景下Hibernate的异常会被Spring的DataAccessException上层包装，无法直接被Hibernate异常的处理方法捕获，你可以新增DataAccessException的捕获方法，提取原始异常再做对应处理，示例如下：

@ExceptionHandler(org.springframework.dao.DataAccessException.class)
public ResponseEntity<Map<String, Object>> handleDataAccessException(org.springframework.dao.DataAccessException e) {
    Throwable rootCause = e.getRootCause();
    // 判断原始异常是否为Hibernate异常
    if (rootCause instanceof ConstraintViolationException hibernateEx) {
        Map<String, Object> result = new HashMap<>();
        result.put("code", 400);
        result.put("msg", String.format("数据约束冲突：%s", hibernateEx.getSQLException().getMessage()));
        return new ResponseEntity<>(result, HttpStatus.BAD_REQUEST);
    }
    // 其他数据访问异常走通用逻辑
    Map<String, Object> result = new HashMap<>();
    result.put("code", 500);
    result.put("msg", "数据操作失败：" + e.getMessage());
    return new ResponseEntity<>(result, HttpStatus.INTERNAL_SERVER_ERROR);
}

注意事项

异常捕获存在优先级：异常类型范围越小的处理方法优先级越高，你新增的Hibernate特定异常处理方法会优先于通用Exception处理方法被触发，不会和现有逻辑冲突
生产环境建议不要直接返回原始数据库错误信息给前端，避免泄露表结构、字段等敏感信息，可以提前预设约束名和用户友好提示的映射关系，比如遇到user.username唯一键冲突时直接返回「该用户名已被注册」
如果你使用的是Spring Boot 3+版本，原javax.persistence包已迁移到jakarta.persistence，需要注意导入的依赖包路径和你的项目版本匹配

内容的提问来源于stack exchange，提问作者valérie jacques