当前位置： 首页 > news >正文

JAVA中Spring全局异常处理@ControllerAdvice解析

news 来源：原创 2025/4/29 9:29:04

一、@ControllerAdvice基础概念

1. 什么是@ControllerAdvice？

@ControllerAdvice是Spring 3.2引入的注解，用于定义全局控制器增强组件，主要功能包括：

  • 全局异常处理（最常用）
  • 全局数据绑定
  • 全局数据预处理

2. 核心作用

  • 集中处理控制器层异常
  • 避免重复的异常处理代码
  • 统一API错误响应格式
  • 减少try-catch块污染业务代码

二、基础全局异常处理实现

1. 最小实现示例

@ControllerAdvice
public class GlobalExceptionHandler {@ExceptionHandler(Exception.class)@ResponseBodypublic ResponseEntity<ErrorResponse> handleException(Exception ex) {ErrorResponse error = new ErrorResponse(HttpStatus.INTERNAL_SERVER_ERROR.value(),"服务器内部错误",ex.getMessage());return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);}
}// 统一错误响应DTO
@Data
@AllArgsConstructor
class ErrorResponse {private int status;private String error;private String message;private long timestamp = System.currentTimeMillis();
}

2. 处理特定异常

@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<ErrorResponse> handleResourceNotFound(ResourceNotFoundException ex) {ErrorResponse error = new ErrorResponse(HttpStatus.NOT_FOUND.value(),"资源未找到",ex.getMessage());return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
}

三、高级配置技巧

1. 限定控制器范围

// 只处理指定包下的控制器
@ControllerAdvice(basePackages = "com.example.web.controllers")// 只处理带有特定注解的控制器
@ControllerAdvice(annotations = RestController.class)// 只处理指定类
@ControllerAdvice(assignableTypes = {UserController.class, ProductController.class})

2. 异常处理优先级

Spring会按照最具体到最通用的顺序匹配@ExceptionHandler：

@ExceptionHandler(FileUploadException.class)  // 优先匹配
public ResponseEntity<?> handleFileUpload(FileUploadException ex) { ... }@ExceptionHandler(IOException.class)          // 次级匹配
public ResponseEntity<?> handleIO(IOException ex) { ... }@ExceptionHandler(Exception.class)            // 兜底处理
public ResponseEntity<?> handleGeneral(Exception ex) { ... }

3. 获取请求上下文

通过注入请求对象获取更多信息：

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleException(Exception ex, WebRequest request) {String path = ((ServletWebRequest)request).getRequest().getRequestURI();ErrorResponse error = new ErrorResponse(HttpStatus.INTERNAL_SERVER_ERROR.value(),"处理请求[" + path + "]时发生错误",ex.getMessage());return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
}

四、常见异常处理模式

1. 业务异常处理

@ExceptionHandler(BusinessException.class)
public ResponseEntity<ErrorResponse> handleBusinessException(BusinessException ex) {ErrorResponse error = new ErrorResponse(ex.getErrorCode(),ex.getErrorType(),ex.getMessage());return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST);
}

2. 数据校验异常

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ErrorResponse> handleValidationException(MethodArgumentNotValidException ex) {List<String> errors = ex.getBindingResult().getFieldErrors().stream().map(FieldError::getDefaultMessage).collect(Collectors.toList());ErrorResponse error = new ErrorResponse(HttpStatus.BAD_REQUEST.value(),"参数校验失败",errors.toString());return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST);
}

3. 认证授权异常

@ExceptionHandler({AccessDeniedException.class,AuthenticationException.class
})
public ResponseEntity<ErrorResponse> handleAuthException(RuntimeException ex) {HttpStatus status = ex instanceof AccessDeniedException ? HttpStatus.FORBIDDEN : HttpStatus.UNAUTHORIZED;ErrorResponse error = new ErrorResponse(status.value(),"权限不足",ex.getMessage());return new ResponseEntity<>(error, status);
}

五、最佳实践建议

1. 异常分类处理

建议将异常分为几大类分别处理：

异常类型处理方式HTTP状态码
业务异常返回具体错误信息400-499
系统异常记录日志，返回通用错误500
第三方服务异常记录日志，返回服务不可用503
参数校验异常返回详细校验错误400

2. 日志记录策略

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleException(Exception ex, HttpServletRequest request) {log.error("请求[{} {}]处理失败", request.getMethod(), request.getRequestURI(), ex);// ...返回错误响应
}

3. 生产环境与开发环境差异

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleException(Exception ex,Environment env) {boolean isProd = Arrays.asList(env.getActiveProfiles()).contains("prod");String message = isProd ? "服务器错误，请联系管理员" : ex.getMessage();// ...返回错误响应
}

六、原理深度解析

1. 实现原理

@ControllerAdvice的工作原理：

  1. 通过@ControllerAdvice标记的类会被ExceptionHandlerExceptionResolver识别
  2. Spring初始化时会收集所有@ExceptionHandler方法
  3. 当控制器抛出异常时，DispatcherServlet会：
    • 查找当前控制器内的@ExceptionHandler方法
    • 如果没有，则查找@ControllerAdvice中的处理方法
    • 按异常类型匹配最具体的方法

2. 核心组件协作

[DispatcherServlet]|v
[HandlerExceptionResolver]||-- [ExceptionHandlerExceptionResolver] (处理@ExceptionHandler)|-- [ResponseStatusExceptionResolver] (处理@ResponseStatus)`-- [DefaultHandlerExceptionResolver] (处理Spring标准异常)

3. 执行顺序

  1. @ExceptionHandler方法（当前控制器内）
  2. @ControllerAdvice中的@ExceptionHandler方法
  3. @ResponseStatus异常
  4. Spring默认异常处理

七、常见问题解决方案

1. 异常处理不生效

可能原因：

  • 未启用注解驱动：确保配置了@EnableWebMvc或<mvc:annotation-driven/>
  • 包扫描问题：@ControllerAdvice类未被Spring管理
  • 异常被捕获：上游代码已经catch了异常

2. 处理多个相同类型异常

@ExceptionHandler({IllegalArgumentException.class, IllegalStateException.class})
public ResponseEntity<?> handleIllegal(RuntimeException ex) {// 统一处理多种相似异常
}

3. 自定义异常解析器

如需更复杂控制，可以实现HandlerExceptionResolver：

@Component
public class CustomExceptionResolver implements HandlerExceptionResolver {@Overridepublic ModelAndView resolveException(HttpServletRequest request,HttpServletResponse response,Object handler,Exception ex) {// 自定义异常处理逻辑return ...;}
}

八、Spring Boot增强支持

1. 错误属性配置

application.properties:

server.error.include-message=always
server.error.include-stacktrace=on_param
server.error.include-binding-errors=always

2. 自定义ErrorController

@Controller
@RequestMapping("${server.error.path:${error.path:/error}}")
public class CustomErrorController implements ErrorController {@RequestMappingpublic ResponseEntity<ErrorResponse> handleError(HttpServletRequest request) {HttpStatus status = getStatus(request);ErrorResponse error = new ErrorResponse(status.value(),"自定义错误处理",(String)request.getAttribute("javax.servlet.error.message"));return new ResponseEntity<>(error, status);}private HttpStatus getStatus(HttpServletRequest request) {Integer code = (Integer) request.getAttribute("javax.servlet.error.status_code");return code != null ? HttpStatus.valueOf(code) : HttpStatus.INTERNAL_SERVER_ERROR;}
}

九、性能优化建议

  1. 减少@ControllerAdvice扫描范围：精确指定basePackages
  2. 避免在异常处理中进行IO操作：如数据库写入
  3. 使用响应缓存：对相同异常返回缓存响应
  4. 异步异常处理：对耗时处理使用@Async
@ExceptionHandler(ReportableException.class)
@Async
public CompletableFuture<ResponseEntity<?>> handleReportable(ReportableException ex) {// 异步处理可报告异常reportService.sendReport(ex);return CompletableFuture.completedFuture(ResponseEntity.badRequest().build());
}

通过合理使用@ControllerAdvice进行全局异常处理，可以显著提高Spring应用的健壮性和可维护性，同时为客户端提供一致的错误响应格式。

相关文章：

  • 说一下react更新的流程
  • TCP/IP模型（互联网协议模型）
  • 大模型相关问题解答
  • 系统优化双引擎：正负反馈如何驱动系统进化？
  • 用远程代理模式轻松实现远程服务调用，打开编程新大门
  • 第十九节：编码实操题-手写简易响应式系统
  • 《Masked Autoencoders Are Scalable Vision Learners》---CV版的BERT
  • 信号完整性简介第一篇
  • 数据可视化大屏——物流大数据服务平台
  • 正常流布局
  • 武装Burp Suite工具：APIKit插件_接口安全扫描.
  • 高级词汇（托福/雅思少见）
  • KBEngine 源代码分析（二）：协议注册和处理
  • 明远智睿SSD2351开发板：开启工业控制新征程
  • 如何设置端口映射？内网IP映射到外网访问，附无公网ip端口映射工具方法
  • tensor 的计算操作
  • AUTOSAR图解==＞AUTOSAR_RS_InteractionWithBehavioralModels
  • Kafka 配置参数性能调优建议
  • 第十四届蓝桥杯Scratch03月stema选拔赛——九九乘法表
  • vite项目tailwindcss4的使用
  • 以“最美通缉犯”为噱头直播？光明网：违法犯罪不应成网红跳板
  • 马上评丨机械停车库成“僵尸库”，设计不能闭门造车
  • 四川邻水县县长石国平拟任县（市、区）党委书记
  • 上海明天起进入“升温通道”，五一假期冲刺33℃
  • 日均新开三家“首店”，上海的“首发经济”密码是什么？
  • 航天科技集团质量技术部部长严泽想升任集团副总经理