Spring MVC注解全局异常处理教程

本文深入讲解了Spring MVC中基于@ControllerAdvice和@ExceptionHandler注解实现全局异常处理的核心方案，涵盖如何统一捕获各类异常、定制响应格式与HTTP状态码、安全记录日志、适配REST接口及异步场景等关键实践，帮助开发者告别零散的try-catch，构建健壮、规范、可维护的Web应用错误处理体系。

Spring MVC 提供了基于注解的全局异常处理机制，无需 XML 配置，通过 @ControllerAdvice 和 @ExceptionHandler 即可统一捕获和响应各类异常。

使用 @ControllerAdvice 定义全局异常处理器

@ControllerAdvice 是一个增强型控制器切面，作用于所有 @Controller 类。它本身不处理请求，但可集中定义异常处理逻辑、数据绑定规则或模型属性预填充。

• 推荐单独新建一个类（如 GlobalExceptionHandler），添加 @ControllerAdvice 注解
• 可配合 basePackages 属性限定生效范围，例如：@ControllerAdvice(basePackages = "com.example.web")
• 若项目使用 REST 接口，建议同时加 @ResponseBody，确保返回 JSON 而非视图

用 @ExceptionHandler 拦截具体异常类型

在 @ControllerAdvice 类中，每个 @ExceptionHandler 方法负责处理一种或多种异常。Spring 会按继承关系就近匹配（子类优先）。

• 方法参数可接收 Exception、具体异常类型（如 NullPointerException）、HttpServletRequest、HttpServletResponse 或 Model
• 返回值支持 String（视图名）、ResponseEntity（含状态码与响应体）、普通对象（自动转 JSON）
• 示例：拦截业务异常 BusinessException 并返回标准错误结构

统一响应格式与状态码映射

为提升前后端协作效率，建议定义统一的响应实体（如 ApiResponse），并在异常处理器中封装错误码、消息和时间戳。

• 对系统级异常（如 NullPointerException、IllegalArgumentException）记录日志并返回 500 或 400，避免暴露堆栈信息给前端
• 对 HttpRequestMethodNotSupportedException、HttpMediaTypeNotAcceptableException 等 Spring 内置异常，也可针对性处理并返回友好提示
• 配合 @ResponseStatus 注解可快速设置 HTTP 状态码，适用于简单场景

补充：异常处理顺序与注意事项

Spring MVC 异常处理有明确优先级：局部 @ExceptionHandler（在 Controller 内） > @ControllerAdvice 中的处理方法 > 默认 Spring 错误页（如 Whitelabel Error Page）。

• 确保异常处理器类被 Spring 扫描到（如放在主启动类同包或子包下，或显式配置 @ComponentScan）
• 若使用 Spring Boot，还需确认未禁用默认错误处理（如未配置 server.error.whitelabel.enabled=false 且未引入自定义 ErrorController）
• 对于异步 Controller（@Async 或返回 CompletableFuture），需额外配置 AsyncUncaughtExceptionHandler 处理未捕获异常

到这里，我们也就讲完了《Spring MVC注解全局异常处理教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！