Spring Boot中@RestControllerAdvice及@ExceptionHandler不生效问题

问题根因排查清单 #

• 确认异常类导入正确：ConstraintViolationException要对应Spring Boot版本导入正确的包，Spring Boot 3+使用jakarta.validation.ConstraintViolationException，2.x版本使用javax.validation.ConstraintViolationException，导错其他包下的同名异常会导致异常匹配规则完全失效。
• 补全参数校验类异常的捕获范围：你当前只捕获了ConstraintViolationException，但@Valid @RequestBody场景下参数校验失败抛出的是MethodArgumentNotValidException，@RequestParam/@PathVariable参数绑定失败、类型转换失败抛出的是BindException/TypeMismatchException，这类异常如果没有被精准捕获，正常会走你写的Exception兜底逻辑，如果兜底逻辑也不触发，优先检查下一项配置。
• 检查@RestControllerAdvice的组件扫描范围：确保CustomExceptionHandler所在的包路径，在Spring Boot启动类的组件扫描范围内。比如启动类在com.xxx.job包下，异常类放在com.xxx.common.handler包时，需要在启动类添加@SpringBootApplication(scanBasePackages = "com.xxx")指定扫描根路径，否则全局增强类不会被Spring容器加载，异常处理逻辑完全不会生效。
• 移除异常处理方法的无效参数：你两个异常处理方法里都声明了HttpResponse response这个多余参数，Spring的@ExceptionHandler标记的方法不支持注入该参数，参数绑定失败会导致异常处理方法初始化失败，直接删掉该参数即可。
• 确认异常发生的链路位置：如果异常是在Servlet过滤器、Spring Security拦截器链中抛出的（比如认证失败、请求格式非法被过滤器提前拦截），这类异常不会进入DispatcherServlet的处理流程，@RestControllerAdvice无法捕获，需要单独在过滤器/安全配置中实现异常处理逻辑。

修正后的全局异常处理代码 #

@RestControllerAdvice
@Slf4j
public class CustomExceptionHandler {

    // 处理@RequestParam/@PathVariable上约束注解触发的校验异常
    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<Map<String, String>> constraintViolationHandler(ConstraintViolationException ex){
      Map<String, String> res = new HashMap<>();
      res.put("message", ex.getMessage());
      log.error("参数校验异常:{}", ex.getMessage());
      return new ResponseEntity<>(res, HttpStatus.BAD_REQUEST);
    }

    // 处理@RequestBody参数校验失败抛出的异常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> methodArgumentNotValidHandler(MethodArgumentNotValidException ex){
        String errMsg = ex.getBindingResult().getFieldErrors().stream()
                .map(FieldError::getDefaultMessage)
                .collect(Collectors.joining(";"));
        Map<String, String> res = new HashMap<>();
        res.put("message", errMsg);
        log.error("请求体参数校验异常:{}", errMsg);
        return new ResponseEntity<>(res, HttpStatus.BAD_REQUEST);
    }

    // 兜底处理所有未被精准捕获的异常，统一返回400状态码
    @ExceptionHandler(Exception.class)
    public ResponseEntity<Map<String, String>> normalExceptionHandler(Exception ex){
        Map<String, String> res = new HashMap<>();
        res.put("message", ex.getMessage());
        log.error("服务异常:{}", ex.getMessage(), ex);
        return new ResponseEntity<>(res, HttpStatus.BAD_REQUEST);
    }
}

注：你原有代码里方法内部创建了存储返回信息的Map，但方法返回值声明为ResponseEntity<String>，属于逻辑疏漏，上述代码已统一修正为返回Map结构。如果需要对ConstraintViolationException返回不同的状态码，直接修改对应方法的HttpStatus枚举值即可。

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