spring boot 全局异常处理捕获 orm 映射异常，核心在于配置 handlerexceptionresolver 并注册 jpaexceptiontranslator。通过实现 jpavendoradapter 或在 persistence.xml 中指定 properties，将底层数据库驱动抛出的原生 sql 异常转换为 spring 的 dataaccessexception 体系。这样在 @controlleradvice 中只需统一拦截 dataaccessexception 即可覆盖包括映射失败在内的所有数据层错误。
如何配置 JPA 异常转换器
要让 ORM 映射异常被全局处理器捕获，必须在持久化单元中启用异常转换机制。以 Hibernate 为例，需要在 persistence.xml 或 application.properties 中设置 hibernate.ejb.exception_handler 属性。该属性指向一个实现了 org.hibernate.engine.jdbc.spi.SqlExceptionHelper 相关接口的类，或者直接使用 Spring 提供的 LocalContainerEntityManagerFactoryBean 来自动装配转换器。当发生字段类型不匹配、外键约束违反等映射级错误时，Hibernate 会抛出 SQLException，转换器将其包装为 InvalidDataAccessApiUsageException 或 ConstraintViolationException，从而进入 Spring 的事务和异常处理流程。
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
version="2.0">
<persistence-unit name="myPU" transaction-type="RESOURCE_LOCAL">
<provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
<jdbc-driver>com.mysql.cj.jdbc.Driver</jdbc-driver>
<properties>
<property name="hibernate.hbm2ddl.auto" value="update"/>
<property name="hibernate.show_sql" value="true"/>
<!-- 关键配置：启用 Spring 的 JPA 异常转换 -->
<property name="javax.persistence.validation.factory"
value="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter"/>
</properties>
</persistence-unit>
</persistence>
上述配置确保了底层 JDBC 异常能被正确翻译。在实际开发中，更常见的做法是在 Java Config 中直接配置 LocalContainerEntityManagerFactoryBean，并通过 setJpaVendorAdapter 注入 HibernateJpaVendorAdapter。这个适配器内部已经包含了 JpaDialect 的实现，能够自动处理异常转换。开发者无需手动编写转换器代码，只需确保事务管理器（如 JpaTransactionManager）正确关联了实体管理器工厂，异常就能沿着调用链向上传播至全局处理器。
如何在 ControllerAdvice 中统一拦截
全局异常处理器通过 @RestControllerAdvice 或 @ControllerAdvice 注解定义，利用 @ExceptionHandler 方法拦截特定类型的异常。对于 ORM 映射异常，最通用的父类是 DataAccessException。由于所有 Spring Data 相关的异常都继承自该类，因此只需编写一个处理 DataAccessException 的方法，即可捕获包括映射异常在内的所有数据访问错误。在处理逻辑中，可以通过 getRootCause() 方法获取原始的 SQLException，从而提取具体的错误码或消息，返回给前端友好的提示信息。
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(DataAccessException.class)
public ResponseEntity<Map<String, String>> handleDataAccessError(
DataAccessException ex) {
// 获取根因，通常是 SQLException
Throwable rootCause = ex.getRootCause();
String errorMsg = "Database error occurred";
if (rootCause instanceof SQLException) {
SQLException sqlEx = (SQLException) rootCause;
// 根据 SQLState 或 Error Code 区分具体映射错误
if (sqlEx.getSQLState() != null && sqlEx.getSQLState().startsWith("23")) {
errorMsg = "Constraint violation: " + sqlEx.getMessage();
} else {
errorMsg = "Mapping or query error: " + sqlEx.getMessage();
}
}
Map<String, String> response = new HashMap<>();
response.put("error", errorMsg);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(response);
}
}
这段代码展示了如何处理 DataAccessException。首先检查根因是否为 SQLException，如果是，则进一步分析 SQLState。SQLState 以 "23" 开头的通常表示完整性约束违反，这往往是 ORM 映射中字段与表结构不一致导致的。其他情况则归类为一般的映射或查询错误。通过这种方式，开发者可以在一个地方集中处理所有数据层的异常，保持业务代码的整洁。需要注意的是，如果使用了 MyBatis 等非 Spring Data JPA 的 ORM 框架，可能需要额外配置 MyBatisExceptionTranslator 来实现类似的异常转换效果。
如何处理特定的映射字段类型不匹配
当 ORM 映射中出现字段类型不匹配时，例如将字符串赋值给整数字段，或者日期格式解析失败，通常会抛出 MethodArgumentNotValidException 或 ConversionFailedException。这些异常虽然也属于数据绑定范畴，但往往发生在请求参数解析阶段，而非持久化阶段。为了准确捕获这类问题，可以在全局异常处理器中单独添加对 ConversionFailedException 的处理方法。该方法可以识别具体的转换失败原因，并返回更精确的错误信息，帮助前端定位是哪个字段的输入格式不正确。
@ExceptionHandler(ConversionFailedException.class)
public ResponseEntity<Map<String, String>> handleConversionError(
ConversionFailedException ex) {
String fieldName = ex.getTargetType().getSimpleName();
String errorMsg = "Type mismatch for field: " + fieldName;
Map<String, String> response = new HashMap<>();
response.put("error", errorMsg);
return ResponseEntity.badRequest().body(response);
}
此方法专门处理类型转换失败的情况。通过 getTargetType() 可以获取目标字段的类型信息，从而生成针对性的错误提示。这种细粒度的处理方式，使得全局异常处理器不仅能捕获底层的数据库异常，还能覆盖上层的参数绑定异常，提供完整的异常覆盖方案。开发者应根据实际业务需求，选择合适的异常类型进行拦截，确保错误信息的准确性和用户体验的良好性。
