MyBatis处理DuplicateKeyException技巧

本文深入解析了 MyBatis 中 DuplicateKeyException 的真实来源与精准捕获策略，指出该异常实为 Spring 对底层数据库驱动原生约束异常（如 MySQL 的 1062 错误或 PostgreSQL 的 23505）的统一包装，强调只有在正确配置 spring-jdbc 和 DataSourceTransactionManager 的前提下才能被自动翻译；文章不仅提供了 Service 层 try-catch 结合 rootCause 和 SQLState/ErrorCode 的健壮判别方案，还对比了全局 @ControllerAdvice 处理的适用场景与陷阱，并一针见血地驳斥了“先查后插”等伪优化做法——既无法规避并发竞态，又牺牲性能与数据一致性，最终引导开发者回归唯一索引兜底本质，同时通过索引命名规范或消息解析应对多唯一键定位难题。

MyBatis 抛出 DuplicateKeyException 的真实来源

它不是 MyBatis 自己抛的，而是 MyBatis 将底层 JDBC 驱动（比如 MySQL 的 com.mysql.cj.jdbc.exceptions.MySQLIntegrityConstraintViolationException 或 PostgreSQL 的 org.postgresql.util.PSQLException）包装后统一转成的 DuplicateKeyException。所以能否捕获，取决于你用的数据库驱动是否被 Spring 的异常翻译器识别——Spring Boot 2.0+ 默认启用，但老项目或手动配 DataSource 时可能没开。

• 确认 spring-jdbc 在 classpath，且用了 DataSourceTransactionManager 或类似事务管理器
• 如果直接用 SqlSessionTemplate 而非 @Mapper 接口，异常不会被自动翻译，得自己 try-catch 原始 JDBC 异常
• MySQL 8.0+ 和某些连接参数（如 serverTimezone=UTC）不影响异常类型，但驱动版本太低（如 mysql-connector-java 5.1.x）可能让异常无法被正确映射

在 Service 层用 try-catch 捕获 DuplicateKeyException

这是最直接、最可控的方式，适合需要差异化响应的场景（比如注册时提示“手机号已被占用”，而不是“操作失败”）。

• 别在 Controller 层 catch —— 业务逻辑和错误语义应该由 Service 定义
• catch DuplicateKeyException 后，可以调用 e.getRootCause() 拿到原始驱动异常，从中提取错误码或消息（MySQL 是 1062，PostgreSQL 是 23505）
• 避免只依赖 getMessage() 做字符串匹配，不同驱动返回格式差异大；优先用 SQLState 或 ErrorCode 判断

try {
    userMapper.insert(user);
} catch (DuplicateKeyException e) {
    Throwable root = e.getRootCause();
    if (root instanceof SQLException) {
        String sqlState = ((SQLException) root).getSQLState(); // MySQL: 23000, PG: 23505
        if ("23505".equals(sqlState) || "23000".equals(sqlState)) {
            throw new BusinessException("用户名已存在");
        }
    }
    throw e;
}

用 @ControllerAdvice 全局统一处理 DuplicateKeyException

适合中后台系统，所有唯一冲突都返回标准错误码（如 409 Conflict）和结构化 message。

• 必须确保你的全局异常处理器能扫到 DuplicateKeyException，它属于 org.springframework.dao.DuplicateKeyException，不是运行时异常，不会被默认的 @ExceptionHandler(RuntimeException.class) 捕获
• 如果用了 Lombok 的 @Data 或其他 AOP，注意异常可能被代理层吞掉；建议在 advice 上加 @Order(Ordered.HIGHEST_PRECEDENCE) 提前拦截
• 不要在 advice 里重新 throw 新异常，除非封装了业务语义；否则直接返回 ResponseEntity.status(409).body(...) 更干净

为什么不能只靠数据库约束 + 忽略异常？

有人想绕过异常处理，改用先 SELECT 再 INSERT（即“检查后执行”），这在并发下必然出错，而且性能差。

• 两次网络往返 + 两次数据库锁，QPS 下降明显，尤其高并发写场景
• 即使加了 SELECT FOR UPDATE，也不能完全避免竞态：事务隔离级别不够（如 READ COMMITTED）时，仍可能漏判
• 唯一索引本身就是为了兜底而存在，放弃它等于放弃数据一致性保障
• 真正该优化的是异常处理路径的响应速度——比如缓存常见冲突字段的校验结果，而非跳过约束

复杂点在于：同一个表可能有多个唯一索引（username、email、phone），而 DuplicateKeyException 不告诉你具体是哪个字段冲突。得靠解析原始异常消息或提前约定索引命名规范（如 uk_user_email），再做字段映射。这点很容易被忽略。

今天关于《MyBatis处理DuplicateKeyException技巧》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！