【Spring】HandlerInterceptor解析

HandlerInterceptor 深度解析

一、核心方法

HandlerInterceptor接口定义了三个核心方法，构成完整的请求生命周期拦截机制：

publicinterfaceHandlerInterceptor{// 1. 请求预处理（Controller执行前）defaultbooleanpreHandle(HttpServletRequestrequest,HttpServletResponseresponse,Objecthandler)throwsException{returntrue;// 返回true继续流程，false中断请求}// 2. 请求后处理（Controller执行后，视图渲染前）defaultvoidpostHandle(HttpServletRequestrequest,HttpServletResponseresponse,Objecthandler,ModelAndViewmodelAndView)throwsException{}// 3. 请求完成回调（视图渲染后）defaultvoidafterCompletion(HttpServletRequestrequest,HttpServletResponseresponse,Objecthandler,Exceptionex)throwsException{}}

执行顺序：多个拦截器时，preHandle()按配置顺序正序执行，而postHandle()和afterCompletion()按逆序执行。

二、主要作用

HandlerInterceptor的核心作用可归纳为：

1.请求预处理

在Controller方法执行前进行通用操作，如权限验证、日志记录、参数修改等。通过返回布尔值决定是否继续执行后续流程。

2.请求后处理

在Controller执行后、视图渲染前对ModelAndView对象进行操作，可修改模型数据或视图属性。

3.资源清理

在整个请求完成后（包括视图渲染）执行资源释放操作，如关闭文件流、释放数据库连接，防止资源泄漏。

三、应用场景

高频场景

特殊场景

• 跨域处理：动态添加CORS响应头
• 请求头统一处理：解析Authorization、X-Request-ID等元数据
• 异常信息记录：在afterCompletion()中捕获并记录控制器抛出的异常

四、注意事项与最佳实践

⚠️ 关键注意事项

1. 执行顺序控制

   • 拦截器执行顺序由注册顺序决定，可使用@Order注解调整优先级（值越小越先执行）
   • 外层拦截器的preHandle()返回false会阻止内层拦截器执行

2. 与Filter的区别

   • HandlerInterceptor：运行于Spring MVC框架内，可访问Spring上下文，精准拦截Controller
   • Filter：基于Servlet规范，更底层，可拦截所有请求（包括静态资源）

3. 与AOP的选型

   • HandlerInterceptor：适用于Web层全局请求处理
   • AOP：适用于业务方法级别的横切关注点（如事务、缓存）

✅ 最佳实践

1. 保持可测试性：将核心业务逻辑抽出到独立的Service或工具类，避免拦截器成为"不可测试的黑盒"

   // 推荐做法if(!authService.checkPermission(user,request.getRequestURI())){log.warn("无权限访问: {}",request.getRequestURI());response.sendRedirect("/403");returnfalse;}

2. 避免臃肿逻辑：不要在拦截器中编写大量业务判断代码

3. 增强可观测性：为拦截器添加日志和Trace ID，便于分布式链路追踪和问题排查

4. 异常处理结合：配合@ControllerAdvice实现全局异常捕获与处理

5. 资源及时释放：必须在afterCompletion()中释放线程本地变量（ThreadLocal），防止内存泄漏

五、典型配置示例

@ConfigurationpublicclassWebConfigimplementsWebMvcConfigurer{@OverridepublicvoidaddInterceptors(InterceptorRegistryregistry){registry.addInterceptor(newAuthInterceptor()).addPathPatterns("/api/ **")// 拦截路径.excludePathPatterns("/api/login","/api/public/ **");// 排除路径}}

通过合理运用HandlerInterceptor，可构建健壮的"请求防火墙"，提升系统的安全性、可维护性与可扩展性。