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

前言

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

java框架零基础从入门到精通的学习路线附开源项目面经等（超全）
【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 使用场景

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

基本的 API 介绍

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

使用 HandlerInterceptor 的步骤

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

2. Demo

在这里插入图片描述

创建一个自定义拦截器类

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: 请求完成，清理资源");}
}

注册拦截器

需要将这个拦截器注册到 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"); // 排除某些路径}
}

创建简单的测试控制器

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

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 "这是登录页面，不会被拦截！";}
}

运行程序并测试

启动 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());}}
}