MyBatis处理DuplicateKeyException技巧

本文深入解析了 MyBatis 中 DuplicateKeyException 的真实来源与高效处理策略，澄清该异常实为数据库驱动（如 MySQL 或 PostgreSQL）抛出、经 Spring 异常翻译器统一包装而成，并非 MyBatis 自主生成；文章系统梳理了正确捕获的前提条件（如确保 spring-jdbc 在类路径、使用 DataSourceTransactionManager、避免 SqlSessionTemplate 绕过翻译），推荐在 Service 层精准 try-catch 并通过 rootCause 提取 SQLState 或错误码实现跨数据库兼容的语义化处理，同时指出全局 @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学习网公众号，给大家分享更多文章知识！