Spring Boot 如何映射数据库约束异常,避免重复实现约束?
可以继续由数据库执行约束校验。全局处理器捕获 DataIntegrityViolationException 后,沿异常链找到 java.sql.SQLException,读取 SQLSTATE,生成应用自己的英文提示。这样无需在 service 中重新实现 UNIQUE 校验,也不必依赖 Hibernate 的异常类型。
如果需要准确返回 Username is already taken,应用就必须知道发生冲突的数据库对象对应哪个业务字段。SQLSTATE 能识别“唯一性冲突”,却无法单独表达“用户名已被占用”。通用提示可以自动覆盖新增约束;字段级提示则需要额外的语义映射。
根据 SQLSTATE 分类,不解析异常文本
当前响应冗长,是因为代码直接将 ex.getMessage() 用作 ProblemDetail.detail。这个字符串可能包含 ORM 包装信息、SQL 和本地化的数据库错误,不适合作为接口文案。
PostgreSQL 建议使用错误码判断错误类型。SQLSTATE 不受错误消息语言影响,因此无需为了让接口返回英语而修改数据库 locale。PostgreSQL 错误码文档
常见约束错误可以这样处理:
| SQLSTATE | 含义 | 可采用的英语提示 |
|---|---|---|
23505 | unique_violation | A value that must be unique is already in use. |
23503 | foreign_key_violation | The operation conflicts with related data. |
23502 | not_null_violation | A required value is missing. |
23514 | check_violation | A value does not satisfy a data constraint. |
这些提示只描述数据库能够确认的事实。例如,引用不存在的数据或删除仍被引用的数据,都可能导致外键异常。因此,通用处理器不应一律提示“关联记录不存在”。
保留 Spring 异常入口,向下读取 JDBC 异常
可以继续处理 DataIntegrityViolationException。Spring 官方也建议通常处理这一父类型,而不是依赖更具体的异常子类。Spring 异常文档
原方案只检查 ex.getCause(),假设 Hibernate 异常恰好位于下一层。实际处理时,应遍历 cause 链;遇到批处理异常时,还应检查 SQLException.getNextException()。通过 SQLException.getSQLState() 和 SQLException.getNextException() 可以分别读取 SQLSTATE 和后续 SQL 异常,无需引用 Hibernate 类。JDBC SQLException 文档
下面的完整示例沿用问题中的 422 响应约定,前提是这些约束错误属于可以反馈给调用方的数据问题。未找到约束类 SQLSTATE 时,返回通用 500。
import java.sql.SQLException;
import java.util.ArrayDeque;
import java.util.Collections;
import java.util.Deque;
import java.util.IdentityHashMap;
import java.util.Set;
import org.springframework.dao.DataIntegrityViolationException;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice
public class DatabaseExceptionHandler {
@ExceptionHandler(DataIntegrityViolationException.class)
public ResponseEntity<ProblemDetail> handle(
DataIntegrityViolationException ex) {
SQLException sql = findConstraintViolation(ex);
HttpStatus status;
String detail;
if (sql == null) {
status = HttpStatus.INTERNAL_SERVER_ERROR;
detail = "The operation could not be completed.";
} else {
status = HttpStatus.UNPROCESSABLE_CONTENT;
detail = switch (sql.getSQLState()) {
case "23505" ->
"A value that must be unique is already in use.";
case "23503" ->
"The operation conflicts with related data.";
case "23502" ->
"A required value is missing.";
case "23514" ->
"A value does not satisfy a data constraint.";
default ->
"The operation violates a data constraint.";
};
}
ProblemDetail problem =
ProblemDetail.forStatusAndDetail(status, detail);
return ResponseEntity.status(status).body(problem);
}
private static SQLException findConstraintViolation(Throwable root) {
Deque<Throwable> pending = new ArrayDeque<>();
Set<Throwable> visited =
Collections.newSetFromMap(new IdentityHashMap<>());
pending.add(root);
while (!pending.isEmpty()) {
Throwable current = pending.removeFirst();
if (!visited.add(current)) {
continue;
}
if (current instanceof SQLException sql) {
String state = sql.getSQLState();
if (state != null && state.startsWith("23")) {
return sql;
}
if (sql.getNextException() != null) {
pending.addLast(sql.getNextException());
}
}
if (current.getCause() != null) {
pending.addLast(current.getCause());
}
}
return null;
}
}
SQLSTATE 的前两位表示错误类别,23 表示完整性约束错误。新增 UNIQUE 约束后,处理器仍会进入 23505 分支,无需修改;其他未单独列出的 23 类错误使用通用提示。
代码不再直接依赖 Hibernate 异常类,但错误码映射仍以 PostgreSQL 为适用背景。更换数据库时,需要重新核对驱动返回的错误码。
具体到用户名的提示,需要业务信息
如果接口只需要提示“某个唯一值已被使用”,上述处理就够了。如果必须指出“用户名已被占用”,可以只为需要精确反馈的约束配置映射,其余约束使用通用提示。
约束名称与文案的映射不会重复执行唯一性校验。数据库仍决定写入是否合法,映射负责把失败原因转换成接口语言。约束是否存在、是否触发,与错误提示如何展示,是两项不同的维护工作。
如果希望绕过 Hibernate 获取约束名称,可以在适配层识别 PostgreSQL JDBC 的 PSQLException,通过 getServerErrorMessage() 取得 ServerErrorMessage,再读取 getConstraint()。这些结构化字段允许为空,使用时需要判空;也不能假设每次 UNIQUE 错误都能直接取得列名。PostgreSQL JDBC 错误字段 API
这会引入 PostgreSQL 驱动依赖,适合集中封装在数据库适配代码中。业务层可以只接收应用定义的错误码,例如 username_taken。
不要根据 user_name_key 的字符串格式猜测 API 字段,也不要解析俄语或英语错误消息。自定义约束名、联合唯一约束、表达式索引,以及数据库列名与请求字段名的差异,都可能让这种推断失效。即使查询数据库元数据找到了相关列,仍需决定它们在接口中如何表达。
提前查询不能替代 UNIQUE 约束
service 中可以先查询用户名是否存在,以改善交互,但这无法保证后续插入成功。两个并发请求可能同时查到用户名不存在,然后同时尝试写入,最终仍需数据库裁决。
因此,不必为了生成错误提示而增加查询。确实需要提前提示时可以查询,但最终写入失败仍要经过异常处理。
确认事务和状态码的处理边界
约束异常可能在 SQL 执行、flush 或事务提交时才出现。应让异常退出失败的事务,再由 Web 层生成响应;不要在已失败的事务里吞掉异常并继续写入。上述处理器适用于最终以 DataIntegrityViolationException 暴露给 MVC 的情况。其他提交异常包装类型需要结合实际异常链处理。
完整性约束失败也不一定都是调用方的责任。例如,应用生成了重复主键,或持久化逻辑漏填内部必需字段,更适合按服务端错误处理。示例中的统一 422 是接口策略,不应仅凭 23505 或 23502 就断定用户输入有误。
对外返回应用控制的文案。诊断时记录 SQLSTATE 和必要的约束信息,并按日志规范处理敏感值。不要继续把完整 ex.getMessage() 放进响应。
备注:内容仅供参考。
