详细分析SpringMvc中HandlerInterceptor拦截器的基本知识（附Demo）

前言

对于Java的基本知识推荐阅读：

1. java框架 零基础从入门到精通的学习路线 附开源项目面经等（超全）
2. 【Java项目】实战CRUD的功能整理（持续更新）

1. 基本知识

HandlerInterceptor 是 Spring MVC 提供的一种机制，用来在请求处理的不同阶段进行拦截

它通常用于日志记录、权限校验、性能监控等操作
继承 HandlerInterceptor 允许定义自定义的逻辑，在请求被处理之前、之后以及完成后执行额外的任务

HandlerInterceptor 接口中包含三个主要方法：

• preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
  在请求处理之前调用（即在控制器方法调用之前）
  返回 boolean 类型，如果返回 true，则继续处理请求；如果返回 false，则中断请求

• postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView)
  在请求被处理之后、视图被渲染之前调用
  用于对 ModelAndView 做进一步的修改或处理

• afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex)
  在整个请求完成后（包括视图渲染完成后）调用
  用于清理资源、记录日志或执行后续的逻辑

HandlerInterceptor 使用场景

1. 日志记录：拦截请求并记录请求信息，如 URL、参数、处理时间等
2. 权限校验：在进入控制器方法之前，检查用户是否有权限访问某个资源
3. 性能监控：统计每个请求的耗时，以便优化性能
4. 会话管理：检查用户会话状态，判断用户是否已经登录

基本的 API 介绍

• HttpServletRequest：表示客户端的请求，可以从中获取请求的 URL、参数、请求体等
• HttpServletResponse：表示服务器端的响应，可以向客户端写入响应数据
• Handler：处理器，通常是控制器方法或其代理对象（通常是 HandlerMethod）
• ModelAndView：封装了数据模型和视图信息，可以在 postHandle 方法中对其进行修改

使用 HandlerInterceptor 的步骤

1. 创建拦截器类：实现 HandlerInterceptor 接口并重写其方法
2. 注册拦截器：在 Spring 配置中，将自定义的拦截器注册到拦截器链中
3. 配置拦截路径：可以选择对哪些 URL 进行拦截，或者排除哪些 URL

2. Demo

1. 创建一个自定义拦截器类

import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.ModelAndView;import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;@Component
public class MyInterceptor implements HandlerInterceptor {// 在控制器处理请求之前调用@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {System.out.println("preHandle: 请求URL -> " + request.getRequestURI());// 这里可以进行权限校验、记录日志等操作// 如果返回 false，请求会被终止return true;}// 在控制器处理请求之后调用，但在视图渲染之前调用@Overridepublic void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {System.out.println("postHandle: 请求处理完毕");}// 在整个请求完成后调用，通常用于资源清理等操作@Overridepublic void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {System.out.println("afterCompletion: 请求完成，清理资源");}
}

2. 注册拦截器

需要将这个拦截器注册到 Spring MVC 中

通常，在配置类中添加拦截器

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;@Configuration
public class WebConfig implements WebMvcConfigurer {@Autowiredprivate MyInterceptor myInterceptor;@Overridepublic void addInterceptors(InterceptorRegistry registry) {// 添加拦截器，并指定拦截路径registry.addInterceptor(myInterceptor).addPathPatterns("/**") // 拦截所有路径.excludePathPatterns("/login", "/register"); // 排除某些路径}
}

3. 创建简单的测试控制器

为了测试拦截器的效果，可以创建一个简单的控制器：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
public class TestController {@GetMapping("/test")public String test() {return "拦截器测试成功！";}@GetMapping("/login")public String login() {return "这是登录页面，不会被拦截！";}
}

4. 运行程序并测试

启动 Spring Boot 应用后，访问 /test URL

将会在控制台看到以下输出：

preHandle: 请求URL -> /test
postHandle: 请求处理完毕
afterCompletion: 请求完成，清理资源

如果访问 /login，因为在 WebConfig 中排除了 /login 路径，拦截器不会生效

总的来说

HandlerInterceptor 是 Spring MVC 中非常有用的拦截器机制，它可以在请求处理的各个阶段执行自定义逻辑

• 常用的拦截器功能包括日志记录、权限检查、性能监控等
• 使用步骤：定义拦截器类、注册拦截器、配置拦截路径

3. 实战解析

@Slf4j // 引入 Lombok 提供的注解，用于简化日志的使用，不需要显式定义 logger 对象。
public class ApiAccessLogInterceptor implements HandlerInterceptor {// 定义一个常量，用于存储处理方法（HandlerMethod）的属性名称，这个属性将在后续的过滤器中使用。public static final String ATTRIBUTE_HANDLER_METHOD = "HANDLER_METHOD";// 定义一个常量，用于存储 StopWatch 对象的属性名称，StopWatch 是用于记录请求耗时的计时器。private static final String ATTRIBUTE_STOP_WATCH = "ApiAccessLogInterceptor.StopWatch";/*** 拦截器的前置处理方法 (preHandle)，在请求处理前调用。* * @param request  当前的 HttpServletRequest 对象，包含了请求信息。* @param response 当前的 HttpServletResponse 对象，包含了响应信息。* @param handler  请求处理器，通常是一个 Controller 中的方法，或其对应的代理对象。* @return 如果返回 true，则继续执行后续的拦截器或目标方法；如果返回 false，则中断请求流程。*/@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {// 记录 HandlerMethod（处理方法），将其存储到 request 属性中，以供后续的过滤器或日志使用。HandlerMethod handlerMethod = handler instanceof HandlerMethod ? (HandlerMethod) handler : null;if (handlerMethod != null) {request.setAttribute(ATTRIBUTE_HANDLER_METHOD, handlerMethod);}// 打印请求日志。如果当前环境不是生产环境（非 prod 环境），则执行日志输出。if (!SpringUtils.isProd()) { // 检查当前是否是生产环境，如果不是则记录日志// 获取请求的查询参数，以键值对的形式存储。Map<String, String> queryString = ServletUtils.getParamMap(request);// 如果请求是 JSON 请求类型，则从请求中提取出请求体。String requestBody = ServletUtils.isJsonRequest(request) ? ServletUtils.getBody(request) : null;// 如果既没有查询参数，也没有请求体，则打印无参数的日志；否则打印包含参数或请求体的日志。if (CollUtil.isEmpty(queryString) && StrUtil.isEmpty(requestBody)) {log.info("[preHandle][开始请求 URL({}) 无参数]", request.getRequestURI());} else {log.info("[preHandle][开始请求 URL({}) 参数({})]", request.getRequestURI(),StrUtil.nullToDefault(requestBody, queryString.toString()));}// 计时操作：为请求创建一个 StopWatch（计时器），并启动它，用于后续计算请求的处理耗时。StopWatch stopWatch = new StopWatch();stopWatch.start();// 将 StopWatch 对象存储到 request 的属性中，以便在 afterCompletion 方法中使用。request.setAttribute(ATTRIBUTE_STOP_WATCH, stopWatch);}return true; // 返回 true，表示允许请求继续往下处理。}/*** 拦截器的后置处理方法 (afterCompletion)，在整个请求处理完成（包括视图渲染完成）之后调用。* * @param request  当前的 HttpServletRequest 对象，包含了请求信息。* @param response 当前的 HttpServletResponse 对象，包含了响应信息。* @param handler  请求处理器，通常是一个 Controller 中的方法，或其对应的代理对象。* @param ex       如果请求处理过程中出现异常，这里可以捕获到。*/@Overridepublic void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {// 打印响应日志。如果当前环境不是生产环境（非 prod 环境），则执行日志输出。if (!SpringUtils.isProd()) {// 从 request 属性中获取在 preHandle 方法中创建的 StopWatch 对象。StopWatch stopWatch = (StopWatch) request.getAttribute(ATTRIBUTE_STOP_WATCH);// 停止计时器，计算请求处理总耗时。stopWatch.stop();// 打印完成请求的日志，包括请求的 URL 和耗时（单位：毫秒）。log.info("[afterCompletion][完成请求 URL({}) 耗时({} ms)]",request.getRequestURI(), stopWatch.getTotalTimeMillis());}}
}

截图如下：