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

Spring MVC异常处理利器：深入理解HandlerExceptionResolver

news 2025/4/29 6:43:05

引言

在 Web 开发中，异常处理是保障系统健壮性和用户体验的关键环节。Spring MVC 提供了多种异常处理机制，其中 HandlerExceptionResolver 是一个强大且灵活的底层工具。本文将深入探讨它的工作原理、使用场景、实战技巧，并通过具体代码示例展示如何全局统一处理异常。

什么是 `HandlerExceptionResolver`？

HandlerExceptionResolver 是 Spring MVC 中用于统一处理控制器方法执行过程中抛出异常的接口。它允许开发者将异常转换为特定的 HTTP 响应，例如：

跳转到自定义错误页面（HTML）
返回结构化的错误 JSON（API 接口）
设置 HTTP 状态码（如 404、500）

通过实现该接口，可以集中管理所有异常，避免在每个控制器中重复编写 try-catch 代码。

核心方法与处理流程：

ModelAndView resolveException(HttpServletRequest request,HttpServletResponse response,Object handler,Exception ex
);

参数：
- request、response：操作 HTTP 请求和响应。
- handler：触发异常的控制器方法。
- ex：抛出的异常对象。
返回值：
- ModelAndView：封装视图和数据，若返回 null 则表示未处理异常，由其他解析器继续处理。

处理流程

控制器方法抛出异常。
Spring MVC 遍历所有注册的 HandlerExceptionResolver。
第一个能处理该异常的解析器（返回非 null）终止流程。
若所有解析器均未处理，则交由容器默认处理（如 Tomcat 的 Whitelabel 错误页）

自定义 `HandlerExceptionResolver` 实战

场景需求

假设项目中需实现以下异常处理逻辑：

Web 请求：跳转到美观的错误页面，并显示友好提示。
API 请求：返回 JSON 格式的错误信息，包含错误码和消息。
特定异常：如 BusinessException 需记录日志并返回自定义 HTTP 状态码。

代码实现

1. 创建自定义解析器

public class GlobalExceptionResolver implements HandlerExceptionResolver, Ordered {@Overridepublic ModelAndView resolveException(HttpServletRequest request,HttpServletResponse response,Object handler,Exception ex) {// 判断请求类型：API 或 Webboolean isApiRequest = request.getRequestURI().startsWith("/api/") || "application/json".equals(request.getHeader("Accept"));if (isApiRequest) {return handleApiException(response, ex);} else {return handleWebException(ex);}}private ModelAndView handleApiException(HttpServletResponse response, Exception ex) {try {response.setContentType("application/json");response.setStatus(500); // 默认状态码// 构建 JSON 响应体Map<String, Object> error = new HashMap<>();error.put("code", 500);error.put("message", "服务异常，请稍后重试");// 针对特定异常细化处理if (ex instanceof BusinessException) {BusinessException bex = (BusinessException) ex;error.put("code", bex.getCode());error.put("message", bex.getMessage());response.setStatus(bex.getHttpStatus().value());}// 写入响应流response.getWriter().write(new ObjectMapper().writeValueAsString(error));} catch (IOException e) {e.printStackTrace();}return new ModelAndView(); // 返回空表示已处理}private ModelAndView handleWebException(Exception ex) {ModelAndView mav = new ModelAndView("error-page"); // 模板路径mav.addObject("errorMsg", ex.getMessage());// 记录日志log.error("Web请求异常: ", ex);return mav;}@Overridepublic int getOrder() {return Ordered.HIGHEST_PRECEDENCE; // 最高优先级}
}

2. 注册解析器

@Configuration
public class WebMvcConfig {@Beanpublic HandlerExceptionResolver globalExceptionResolver() {return new GlobalExceptionResolver();}
}

3. HTML 错误页模板（Thymeleaf）

resources/templates/error-page.html：

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><title>错误提示</title>
</head>
<body><h1>抱歉，系统开小差了！</h1><p th:text="${errorMsg}"></p><a href="/">返回首页</a>
</body>
</html>

高级技巧与最佳实践

1. 优先级控制

通过实现 Ordered 接口或使用 @Order 注解，确保自定义解析器优先于 Spring 默认解析器执行。例如：

@Override
public int getOrder() {return Ordered.HIGHEST_PRECEDENCE; // 值越小，优先级越高
}

2. 异常日志记录

在解析器中统一记录异常日志，便于问题排查：

@Override
public ModelAndView resolveException(...) {log.error("请求路径: {}, 异常信息: {}", request.getRequestURI(), ex.getMessage(), ex);// ...处理逻辑
}

3. 区分异常类型

针对不同异常定制处理逻辑，提升用户体验：

if (ex instanceof ResourceNotFoundException) {response.setStatus(404);error.put("message", "请求的资源不存在");
} else if (ex instanceof AccessDeniedException) {response.setStatus(403);error.put("message", "无权访问");
}

与 `@ControllerAdvice` 对比：

特性	`HandlerExceptionResolver`	`@ControllerAdvice` + `@ExceptionHandler`
灵活性	更底层，可完全控制处理流程	基于注解，较为简洁
适用场景	需要动态判断响应类型（如 HTML/JSON）	同一异常类型固定返回一种响应格式
代码侵入性	需手动注册解析器	无侵入，通过注解声明
优先级控制	通过 `Ordered` 接口精细控制	默认按 `@Order` 注解或 Bean 顺序