JPA多列唯一约束违反时自定义友好错误消息解决方案

你写在save()外层的try-catch永远抓不到唯一约束异常，核心原因是JPA和Spring事务的执行机制：

• 调用JpaRepository.save()时，Hibernate不会立刻把变更同步到数据库，只是将修改后的实体放入一级持久化缓存，标记为待更新状态
• 被@Transactional标记的方法，只有在方法内所有业务逻辑执行完毕、正常返回后，才会进入事务提交阶段，此时Hibernate才会将缓存中所有待执行的SQL批量刷入数据库执行，唯一约束冲突的异常就是在这个刷盘、提交的节点抛出的
• 等异常抛出的时候，你写在方法内部的try-catch块早就随着方法执行结束退出调用栈了，自然不可能捕获到提交阶段的异常。

不需要在每个业务方法里硬写try-catch，用全局统一拦截+可选前置校验的方式即可实现无侵入的友好错误提示，覆盖所有约束冲突场景。

方案1：全局异常处理器兜底（推荐，零业务侵入） #

不管是Web接口、还是其他请求链路里抛出的数据库约束异常，都可以通过全局异常处理器统一拦截、转换为用户能看懂的提示，不需要修改现有业务逻辑：

1. 编写全局异常处理类，拦截Spring封装后的数据完整性异常：

import org.springframework.dao.DataIntegrityViolationException;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.util.Map;

@RestControllerAdvice
public class GlobalExceptionHandler {

    // 自定义业务异常，统一前后端交互的错误格式
    public static class BizException extends RuntimeException {
        private final int errorCode;
        public BizException(int errorCode, String message) {
            super(message);
            this.errorCode = errorCode;
        }
        public int getErrorCode() {
            return errorCode;
        }
    }

    @ExceptionHandler(DataIntegrityViolationException.class)
    public ResponseEntity<Map<String, Object>> handleConstraintViolation(DataIntegrityViolationException e) {
        String rootCauseMsg = getNestedRootMessage(e);
        // 匹配你定义的联合唯一约束名，精准识别冲突场景
        if (rootCauseMsg != null && rootCauseMsg.contains(Column.UNIQUE_COLUMN_BOARD_POSITION)) {
            return ResponseEntity.badRequest().body(Map.of(
                    "code", 400,
                    "msg", "同一看板下的列位置不能重复，请调整后重试"
            ));
        }
        // 其他数据完整性异常返回通用提示
        return ResponseEntity.internalServerError().body(Map.of(
                "code", 500,
                "msg", "数据操作异常，请稍后重试"
        ));
    }

    // 递归获取最内层异常的信息，约束名只会出现在数据库驱动抛出的最底层异常中
    private String getNestedRootMessage(Throwable throwable) {
        Throwable root = throwable;
        while (root.getCause() != null) {
            root = root.getCause();
        }
        return root.getMessage();
    }
}

2. 如果是单元测试、异步任务这类非Web场景，需要在方法内捕获异常的话，可以在save()调用后手动触发Hibernate刷盘，把异常抛出时机提前到方法执行阶段：

@Service
public class ColumnService {
    private final ColumnRepository columnRepository;
    private final EntityManager entityManager;

    // 构造函数注入省略

    @Transactional
    @NonNull
    public Column update(long columnId, @NonNull Column transientColumn) {
        Column persistentColumn = get(columnId);
        persistentColumn.setTitle(transientColumn.getTitle());
        persistentColumn.setPosition(transientColumn.getPosition());
        Column saved = columnRepository.save(persistentColumn);
        // 手动触发SQL同步到数据库，约束冲突会在此处立刻抛出
        entityManager.flush();
        return saved;
    }
}

不推荐把异常处理逻辑散落在各个业务方法中，全局统一处理的维护成本低、逻辑一致性更好。

方案2：新增业务前置校验（可选，优化体验） #

对于可预见的唯一约束冲突，可以在执行更新前加一层业务校验，提前拦截非法请求，比等数据库抛异常性能更好：

1. 在ColumnRepository中新增查询方法：

public interface ColumnRepository extends JpaRepository<Column, Long> {
    // 统计同一看板下、占用目标位置、且不是当前正在更新的列的数量
    boolean existsByBoardIdAndPositionAndIdNot(Long boardId, Integer position, Long excludedColumnId);
}

2. 在update方法执行更新逻辑前加入校验：

// 取当前列所属的看板ID
Long boardId = persistentColumn.getBoard().getId();
Integer targetPosition = transientColumn.getPosition();
boolean positionOccupied = columnRepository.existsByBoardIdAndPositionAndIdNot(boardId, targetPosition, columnId);
if (positionOccupied) {
    throw new GlobalExceptionHandler.BizException(400, "同一看板下的列位置不能重复，请调整后重试");
}

注意：前置校验不能替代数据库唯一约束和全局异常兜底，高并发场景下依然可能出现两个请求同时通过校验、最终触发数据库约束冲突的情况，两层防护都要保留。

内容的提问来源于stack exchange，提问作者Rafael Lima