SpringBoot配置拦截器怎么做？拦截器配置方法详解

Spring Boot配置拦截器的核心结论

Spring Boot配置拦截器的本质是通过实现HandlerInterceptor接口定义拦截逻辑，再通过WebMvcConfigurer注册到Spring MVC的拦截器链中。 整个过程只需三个步骤：创建拦截器类、注册拦截器、指定拦截与放行路径，相比Filter（过滤器），拦截器能够访问Spring容器中的Bean，更适合做权限校验、日志记录、接口鉴权等业务级操作。

拦截器在Spring Boot中的定位与价值

拦截器与过滤器的核心区别

很多开发者混淆拦截器与过滤器,实际两者在架构层次上有本质差异：

• 过滤器（Filter） 属于Servlet规范，作用于Web容器层面，对所有请求生效，无法获取Spring MVC的Handler方法信息。
• 拦截器（Interceptor） 属于Spring MVC框架，作用于DispatcherServlet之后、Handler执行之前，能够访问Controller方法、参数、返回值，并且天然支持依赖注入。

在业务实践中，接口签名校验、JWT鉴权、接口耗时统计、操作日志记录等场景应优先使用拦截器，因为可以精准控制到具体某个Controller方法，配合注解可以实现非常灵活的权限控制。

Spring Boot配置拦截器的完整实战

第一步：创建自定义拦截器类

实现HandlerInterceptor接口，核心方法有三个：

• preHandle：请求进入Controller之前执行，返回false则中断请求。
• postHandle：Controller执行完毕、视图渲染之前执行。
• afterCompletion：整个请求完成后执行，适合做资源清理和日志记录。

以下是一个完整的JWT鉴权拦截器示例：

@Component
public class AuthInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object
 handler) throws Exception {
        // 放行预检请求
        if ("OPTIONS".equalsIgnoreCase(request.getMethod())) {
            return true;
        }
        // 从请求头获取token
        String token = request.getHeader("Authorization");
        if (token == null || !token.startsWith("Bearer ")) {
            response.setStatus(401);
            response.getWriter().write("{"code":401,"msg":"未登录或token已过期"}");
            return false;
        }
        // 校验token逻辑，可通过注入Redis或JwtUtil实现
        return true;
    }
}

第二步：注册拦截器到MVC配置

通过实现WebMvcConfigurer接口完成注册：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Autowired
    private AuthInterceptor authInterceptor;
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(authInterceptor)
                .addPathPatterns("/api/")      // 拦截所有api接口
                .excludePathPatterns("/api/login", "/api/register", "/error");  // 放行路径
    }
}

这里有一个容易踩坑的点：拦截路径配置的是Spring MVC的路径规则，而不是URL正则表达式。 /api/表示匹配/api/下的所有层级路径，而/api/只匹配一层。

第三步：处理静态资源放行问题

Spring Boot默认的静态资源路径（/static、/public、/resources等）不会经过DispatcherServlet，因此静态资源默认不会被拦截器拦截，但如果你的项目中静态资源通过Controller转发访问，则需要在excludePathPatterns中显式声明。

拦截器配置的进阶优化方案

拦截器链顺序控制

多个拦截器同时注册时,执行顺序遵循先进先出原则（preHandle按注册顺序执行，afterCompletion逆序执行），在电商系统中，通常将

登录鉴权拦截器放在最前，日志拦截器紧随其后，这样能保证未登录请求不会产生无效日志。

基于注解的拦截器增强

仅靠路径匹配无法实现细粒度控制,更专业的做法是自定义注解配合拦截器：

• 创建@RequirePermission注解，标注在Controller方法上。
• 在拦截器的preHandle中通过HandlerMethod获取注解，进行权限校验。
• 实现“路径白名单 + 方法级权限”的双层控制体系。

异步请求的拦截注意点

Spring Boot 2.x后支持异步请求，拦截器在异步请求的preHandle返回true后，postHandle不会立即执行，而是等异步任务完成后再触发，配置AsyncHandlerInterceptor的afterConcurrentHandlingStarted方法可以处理异步场景。

酷番云实战经验案例

某电商平台在酷番云服务器上部署Spring Boot应用时，遭遇了拦截器“失效”问题，应用通过Nginx反向代理对外提供服务，运维同事在Nginx层配置了静态资源缓存规则，导致部分动态请求被错误缓存，跳过拦截器直达Controller，造成未授权访问风险。

解决方案如下：

• 在酷番云控制台调整Nginx配置,关闭对/api/路径的缓存。
• 将拦截器中的token校验逻辑升级为“双token校验”（Access Token + Refresh Token），并利用酷番云Redis服务存储token状态，实现分布式会话管理。
• 同时将拦截器的日志输出接入酷番云日志服务,方便实时排查鉴权失败请求。

核心经验：云环境下的拦截器配置不仅要关注应用本身，还要结合前置的负载均衡、CDN缓存策略综合设计。 建议将所有敏感接口统一走/api/前缀，在Nginx层和拦截器层做双重校验，形成纵深防御体系。

常见异常与排查指南

拦截器不生效通常有三大原因：

• 启动类所在包没有扫描到WebConfig配置类，检查@ComponentScan扫描范围。
• 拦截路径写错,例如将/api/误写为/api/。
• Spring Boot版本升级后配置失效，检查是否有多个WebMvcConfigurer实现冲突，可使用@Primary注解指定优先级。

preHandle返回false后请求直接中断，此时页面无任何响应，建议在返回false前使用response.sendError()或response.getWriter().write()返回明确的JSON错误信息，而不是静默中断。

相关问答模块

拦截器里能否直接使用@Autowired注入Service？

可以，但需要满足两个前提：拦截器类本身被Spring容器管理（标注@Component或@Configuration注册），且注入的Service类也在Spring容器中，需要注意的是，拦截器实例化时间早于Controller，注入的Bean必须是单例且不依赖request作用域，如果遇到注入为空，检查是否手动new了拦截器对象，必须通过@Autowired注入或从容器中获取。

拦截器执行了，但Controller没有被执行是什么原因？

最常见的原因是preHandle返回了false，此时请求被中断，后续的postHandle和afterCompletion以及Controller都不会执行，排查思路：在preHandle中打日志确认返回值；检查是否有多个拦截器链式执行，其中一个拦截器返回false会导致整个链路中断；确认response是否已提交，如果已提交则后续操作无效。

你在Spring Boot拦截器配置中遇到过什么奇怪的问题？是路径匹配失效还是Bean注入失败？欢迎在评论区分享你的踩坑经历，一起讨论解决方案。