DuplicateKeyException 实际由数据库驱动抛出，MyBatis 仅做包装；Spring 通过异常翻译器将其统一转换，需确保 spring-jdbc 在 classpath 且配置了 DataSourceTransactionManager。
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），再做字段映射。这点很容易被忽略。
