详细讲解 Spring MVC 的 HandlerInterceptor 接口

目录一、核心定位二、接口完整定义三、三个核心方法详解执行顺序 作用1. preHandle () —— 【请求前置处理】2. postHandle () —— 【请求后置处理】3. afterCompletion () —— 【请求完成清理】四、执行流程生命周期多个拦截器执行顺序五、常用实现方式方式 1直接实现 HandlerInterceptor方式 2继承 HandlerInterceptorAdapter已废弃六、拦截器注册配置关键常用配置项七、拦截器 VS 过滤器Filter八、经典使用场景九、注意事项总结HandlerInterceptor是Spring MVC 核心的拦截器接口作用类似于 Web 开发中的过滤器Filter但更贴合 Spring MVC 生命周期专门用于对控制器Controller请求进行预处理、后处理、完成清理。简单说它可以在请求进入 Controller 之前、Controller 执行完毕之后、页面渲染完成之后三个节点插入自定义逻辑。一、核心定位属于 Spring MVC 组件只拦截进入控制器的请求不拦截静态资源可配置基于AOP 思想实现请求的横向切面处理日志、登录校验、权限控制等是一个接口开发时需要实现它并重写方法必须注册到 Spring MVC 容器才能生效二、接口完整定义public interface HandlerInterceptor { // 1. 请求进入 Controller 之前执行预处理 default boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { return true; } // 2. Controller 执行完毕视图渲染之前执行后处理 default void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception { } // 3. 整个请求完全结束视图渲染完毕后执行清理 default void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception { } }三个方法都是default空实现实现类可以按需重写不用全部实现。三、三个核心方法详解执行顺序 作用1. preHandle () —— 【请求前置处理】执行时机DispatcherServlet收到请求 → 找到对应 Controller →执行 Controller 方法之前核心作用登录校验、权限校验请求日志记录参数校验、请求头校验拦截非法请求直接返回响应返回值true放行继续执行后续拦截器 Controllerfalse拦截请求终止不会进入 Controller参数说明handler实际要执行的处理器Controller 方法2. postHandle () —— 【请求后置处理】执行时机Controller 方法执行完毕 →返回 ModelAndView 之后→视图JSP/Thymeleaf渲染之前核心作用统一修改响应数据往 Model 中添加公共数据全局变量对 Controller 返回结果做统一处理注意如果 Controller 抛出异常此方法不会执行多个拦截器时执行顺序与preHandle相反3. afterCompletion () —— 【请求完成清理】执行时机整个请求完全结束视图渲染完成 / 请求响应完毕之后核心作用资源清理关闭流、删除临时文件记录请求耗时统一异常日志记录特点无论是否抛出异常一定会执行适合做最终收尾工作四、执行流程生命周期一次完整请求的执行顺序请求 → preHandle() → Controller 执行 → postHandle() → 视图渲染 → afterCompletion() → 响应结束多个拦截器执行顺序假设配置了 3 个拦截器A、B、CpreHandleA → B → CController执行postHandleC → B → AafterCompletionC → B → A栈结构先进后出五、常用实现方式方式 1直接实现 HandlerInterceptorComponent public class LoginInterceptor implements HandlerInterceptor { // 登录校验 Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 从 session 获取用户信息 Object user request.getSession().getAttribute(loginUser); if (user null) { // 未登录拦截并跳转 response.sendRedirect(/login); return false; } // 已登录放行 return true; } }方式 2继承 HandlerInterceptorAdapter已废弃Spring 5 之后推荐直接实现接口接口支持 default 方法不再使用适配器。六、拦截器注册配置关键拦截器必须注册才能生效使用WebMvcConfigurer配置Configuration public class WebConfig implements WebMvcConfigurer { Autowired private LoginInterceptor loginInterceptor; Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(loginInterceptor) .addPathPatterns(/**) // 拦截所有请求 .excludePathPatterns( // 放行请求 /login, /register, /static/**, // 静态资源 /error ); } }常用配置项addPathPatterns(/**)拦截所有请求excludePathPatterns(/login)排除不拦截的路径order(1)设置拦截器执行顺序数字越小越先执行七、拦截器 VS 过滤器Filter这是面试高频考点必须区分清楚表格对比项HandlerInterceptor拦截器Filter过滤器所属容器Spring MVC 容器Servlet 容器拦截范围只拦截 Controller 请求拦截所有 Web 请求包括静态资源执行时机Spring 容器初始化之后Servlet 容器加载之前依赖 Spring强依赖可使用 Spring 所有 Bean不依赖 Spring方法粒度3 个方法精细控制1 个 doFilter 方法使用场景登录、权限、日志、统一结果编码、跨域、限流、请求包装总结Spring Web 项目优先用HandlerInterceptor通用 Web 功能编码、跨域用Filter八、经典使用场景登录认证未登录拦截跳转登录页权限控制校验用户是否有权限访问接口接口日志记录请求路径、参数、耗时、返回结果防重复提交接口幂等性控制全局数据注入给所有页面注入公共参数请求限流接口访问频率控制九、注意事项preHandle 返回 false 必须处理响应否则浏览器会空白静态资源js/css/img一定要排除否则会被拦截拦截器中异常尽量自己捕获避免影响主流程不要在拦截器中做耗时操作会拖慢请求多个拦截器注意order顺序总结HandlerInterceptor是 Spring MVC请求拦截器用于切面处理 Controller 请求核心 3 个方法preHandle前置、postHandle后置、afterCompletion清理必须实现接口 注册配置才能生效适合做登录、权限、日志、公共数据注入等横向逻辑区别于 Filter更轻量、贴合 Spring、粒度更细