SpringBoot 拦截器基于Spring MVC Interceptor用于请求前置/后置处理、登录校验、权限控制、日志记录等下面分基础实现、多拦截器、常见配置一步步讲解。一、核心流程自定义拦截器类实现HandlerInterceptor接口创建Web 配置类实现WebMvcConfigurer注册拦截器配置拦截路径、放行路径测试验证二、版本环境SpringBoot 2.x / 3.x 通用写法SpringBoot3 仅依赖包无变化1. 依赖常规Web项目即可!-- pom.xml --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency三、第一步自定义拦截器实现HandlerInterceptor包含 3 个核心方法preHandle控制器执行之前执行返回true放行false拦截postHandle控制器执行后、视图渲染前执行afterCompletion请求完全结束视图渲染完毕后执行多用于资源释放importorg.slf4j.Logger;importorg.slf4j.LoggerFactory;importorg.springframework.web.servlet.HandlerInterceptor;importorg.springframework.web.servlet.ModelAndView;importjavax.servlet.http.HttpServletRequest;importjavax.servlet.http.HttpServletResponse;/** * 自定义登录拦截器 */publicclassLoginInterceptorimplementsHandlerInterceptor{privatestaticfinalLoggerlogLoggerFactory.getLogger(LoginInterceptor.class);// 控制器执行前OverridepublicbooleanpreHandle(HttpServletRequestrequest,HttpServletResponseresponse,Objecthandler)throwsException{log.info(【拦截器】请求进入 preHandle地址{},request.getRequestURI());// 示例登录校验从session获取登录用户Objectuserrequest.getSession().getAttribute(loginUser);if(usernull){log.info(【拦截器】未登录拦截请求);// 重定向到登录页 / 前后端分离则返回JSONresponse.sendRedirect(/login);returnfalse;// 拦截请求}returntrue;// 放行}// 控制器执行后视图渲染前OverridepublicvoidpostHandle(HttpServletRequestrequest,HttpServletResponseresponse,Objecthandler,ModelAndViewmodelAndView)throwsException{log.info(【拦截器】执行 postHandle);}// 整个请求完成后最后执行OverridepublicvoidafterCompletion(HttpServletRequestrequest,HttpServletResponseresponse,Objecthandler,Exceptionex)throwsException{log.info(【拦截器】请求结束 afterCompletion);}}四、第二步注册拦截器核心配置新建配置类实现 WebMvcConfigurer重写addInterceptors方法注册拦截器。关键配置说明addPathPatterns()要拦截的路径/**拦截所有请求/api/**拦截 api 下所有接口excludePathPatterns()放行路径登录、静态资源、验证码等importorg.springframework.context.annotation.Configuration;importorg.springframework.web.servlet.config.annotation.InterceptorRegistry;importorg.springframework.web.servlet.config.annotation.WebMvcConfigurer;/** * Web 全局配置类注册拦截器 */ConfigurationpublicclassWebConfigimplementsWebMvcConfigurer{OverridepublicvoidaddInterceptors(InterceptorRegistryregistry){registry.addInterceptor(newLoginInterceptor())// 1. 拦截所有请求.addPathPatterns(/**)// 2. 放行路径登录接口、静态资源、首页等.excludePathPatterns(/login).excludePathPatterns(/static/**).excludePathPatterns(/error);// 放行全局异常页}}注意不要加 EnableWebMvc加了会覆盖 SpringBoot 默认 Web 配置导致静态资源、日期格式化等失效。五、第三步编写测试接口/页面1. 登录控制器模拟登录importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RestController;importjavax.servlet.http.HttpSession;RestControllerpublicclassTestController{// 登录接口放行GetMapping(/login)publicStringlogin(HttpSessionsession){// 模拟登录成功存入sessionsession.setAttribute(loginUser,admin);return登录成功;}// 需拦截的接口GetMapping(/index)publicStringindex(){return首页内容;}}六、测试效果访问http://localhost:8080/index未登录 → 被拦截重定向到/login先访问http://localhost:8080/login登录再次访问/index→ 正常放行控制台打印拦截器日志七、进阶用法1. 多个拦截器执行顺序注册多个拦截器先注册先执行preHandle 顺序注册顺序afterCompletion 逆序OverridepublicvoidaddInterceptors(InterceptorRegistryregistry){// 拦截器1 先执行registry.addInterceptor(newInterceptor1()).addPathPatterns(/**);// 拦截器2 后执行registry.addInterceptor(newInterceptor2()).addPathPatterns(/**);}2. 前后端分离场景返回JSON而非重定向替换preHandle中未登录逻辑返回 JSON 提示if(usernull){response.setContentType(application/json;charsetutf-8);response.getWriter().write({\code\:401,\msg\:\请先登录\});returnfalse;}3. 排除静态资源SpringBoot 默认静态资源目录/static、/public、/resources、/META-INF/resources统一放行.excludePathPatterns(/static/**,/public/**)4. 拦截指定 Controller/接口只拦截/api/user/**下接口.addPathPatterns(/api/user/**)八、常见问题拦截器不生效检查配置类是否加Configuration确认没写EnableWebMvc路径匹配是否正确/**和/*区别/*只拦截一级路径404 页面被拦截手动放行/error路径拦截器无法获取 RequestBody 参数原因流只能读取一次需配合请求体包装器解决。补充SpringBoot3 额外说明SpringBoot3 基于 Spring6API 完全兼容以上代码仅部分包路径变化javax.servlet→jakarta.servlet// SpringBoot3 导入包importjakarta.servlet.http.HttpServletRequest;importjakarta.servlet.http.HttpServletResponse;其余逻辑、注册方式完全不变。