SpringMVC拦截器怎么配置？拦截器配置详细步骤，常见问题解答

<mvc:interceptors>
    <!-- 全局拦截器：拦截所有请求 -->
    <bean class="com.example.interceptor.AuthInterceptor"/>
    <!-- 路径拦截器：只拦截特定路径 -->
    <mvc:interceptor>
        <mvc:mapping path="/api/"/>
        <mvc:exclude-mapping path="/api/login"/>
        <bean class="com.example.interceptor.ApiInterceptor"/>
    </mvc:interceptor>
</mvc:interceptors>

Java Config 方式推荐，类型安全

实现 WebMvcConfigurer 接口并重写 addInterceptors 方法：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new AuthInterceptor())
                .addPathPatterns("/")
                .excludePathPatterns("/login", "/register", "/static/");
    }
}

注解驱动 + 自定义注解精准控制，适合细粒度鉴权

通过自定义注解配合拦截器,实现方法级别的权限控制：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RequiresPermission {
    String value();
}

在拦截器中通过 HandlerMethod 获取注解并校验，这种方式能够将权限逻辑从业务代码中完全剥离，维护性极佳。

拦截器核心方法详解（推荐直接复用的基类）

Spring MVC 提供了 HandlerInterceptor 接口，包含三个默认方法（Java 8+ 默认方法），建议继承 HandlerInterceptorAdapter（旧版）或直接实现接口：

• preHandle：在 Controller 方法执行前调用。返回 true 继续执行，返回 false 则中断请求，适合做登录校验、黑名单拦截、参数预处理。
• postHandle：Controller 执行后、视图渲染前调用，适合修改 ModelAndView、统一添加公共数据。



• afterCompletion：请求完成后回调（无论是否异常），适合清理资源、记录日志、统计耗时。

重要：若 preHandle 返回 false，则后续的 postHandle 和 afterCompletion 都不会执行，且同链路上已执行过 preHandle 的拦截器的 afterCompletion 会逆序执行。

执行顺序与常见误区（干货）

拦截器的执行顺序遵循责任链模式，但存在一个关键细节：

• 若配置了多个拦截器 A、B，则执行顺序为：A.preHandle → B.preHandle → Controller → B.postHandle → A.postHandle → 视图渲染 → B.afterCompletion → A.afterCompletion
• preHandle 顺序执行，postHandle 和 afterCompletion 逆序执行。

常见误区：

• 误区一：认为 postHandle 一定能执行，实际上如果 Controller 抛出异常，postHandle 不会执行，只有 afterCompletion 会执行。
• 误区二：拦截器只拦截 Controller 方法，不拦截静态资源，若需拦截静态资源，需要配置 <mvc:resources> 与拦截器路径同时覆盖，或者直接使用 Filter。
• 误区三：拦截器与过滤器混淆，Filter 属于 Servlet 规范，基于容器，拦截所有请求包括静态资源；拦截器属于 Spring MVC，只针对 DispatcherServlet 路由的处理器。权限校验优先用拦截器，字符编码、CORS 等基础过滤优先用 Filter。

实战：完整登录拦截器 + 性能监控（附代码）

以下代码展示一个可复用的登录校验与性能统计拦截器，同时解决异步请求时 afterCompletion 中获取用户信息可能失效的问题（通过 HandlerMethod 和 ThreadLocal 隔离）：

public class AuthAndMonitorInterceptor implements HandlerInterceptor {
    private static final ThreadLocal<Long> START_TIME = new ThreadLocal<>();
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) 
            throws Exception {
        // 性能监控开始
        START_TIME.set(System.currentTimeMillis());
        // 身份校验逻辑
        if (handler instanceof HandlerMethod) {
            HandlerMethod hm = (HandlerMethod) handler;
            // 检查类/方法上的 @RequiresPermission 注解
            RequiresPermission perm = hm.getMethodAnnotation(RequiresPermission.class);
            if (perm != null && !checkPermission(request, perm.value())) {
                response.setStatus(403);
                response.setContentType("application/json;charset=UTF-8");
                response.getWriter().write("{"code":403,"msg&qu
ot;:"无权限"}");
                return false; // 中断请求，不再执行后续逻辑
            }
        }
        // 如为登录接口或公开接口，放行
        return true;
    }
    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, 
            Object handler, Exception ex) {
        Long start = START_TIME.get();
        if (start != null) {
            long cost = System.currentTimeMillis() - start;
            System.out.println(request.getRequestURI() + " 耗时: " + cost + "ms");
            START_TIME.remove(); // 防止线程池复用导致数据错乱
        }
    }
    private boolean checkPermission(HttpServletRequest request, String perm) {
        // 从 Session 或 Token 中解析权限，这里做简化演示
        return request.getSession().getAttribute("user") != null;
    }
}

配置该拦截器（Java Config）：

registry.addInterceptor(new AuthAndMonitorInterceptor())
        .addPathPatterns("/")
        .excludePathPatterns("/login", "/error", "/static/");

酷番云经验案例：高并发场景下的拦截器线程安全实践

酷番云在服务某金融级客户时遇到一个典型问题：拦截器中使用了非线程安全的成员变量来存储请求上下文，导致高并发下用户数据串号，我们当时给出的方案是结合酷番云云服务器（SSD 高性能实例）进行压测验证，最终落地了以下实践：

1. 禁止在拦截器中定义可变的成员变量，必须使用 ThreadLocal 或在方法栈内传递数据。
2. 对于需要全局共享的只读配置（比如白名单路径列表），使用 volatile 修饰并只读初始化，避免并发失效。
3. 利用酷番云的弹性伸缩能力，在流量高峰前预置多台云服务器，同时利用缓存的 excludePathPatterns 配置热更新通过酷番云对象存储下发配置，拦截器内定期拉取，实现免重启更新拦截规则。
4. 经过压测,性能瓶颈不在拦截器，而在于数据库连接和日志同步写，于是我们将日志改为异步写入酷番云日志服务，拦截器只负责采集，显著提升吞吐量。

核心观点：拦截器配置本身简单，但企业级应用必须关注并发安全、性能监控和可观测性，建议在拦截器内只做轻量级逻辑，杜绝数据库查询、远程调用等耗时操作，如有需要可结合消息队列异步化。

性能对比与最佳实践（E-E-A-T 经验总结）

最佳实践清单：

• 将登录校验和日志监控拆分为两个独立拦截器，遵循单一职责。
• 所有拦截器路径用 覆盖大部分场景，再用 excludePathPatterns 排除登录、静态资源、异常页。
• 在拦截器中不要捕获所有异常，让异常交给 @ControllerAdvice 统一处理。
• 如需在 postHandle 中访问用户信息，务必确保信息存储与当前线程绑定，避免异步线程穿透。

相关问答模块

问题1：Spring MVC 拦截器和 Filter 过滤器有什么区别？什么时候选拦截器？

答：两者本质不同。Filter 是 Servlet 规范的一部分，由容器管理，注册在 web.xml 或 @WebFilter 中，可以拦截一切请求（包括静态资源、JSP）；而拦截器是 Spring MVC 的组件，只拦截进入 DispatcherServlet 的请求，并且可以方便地注入 Spring Bean，对于纯 HTTP 层面的处理（如字符编码、CORS、防 XSS 攻击），优先选择 Filter；对于需要与 Spring 业务上下文交互的逻辑（如权限校验、用户会话检查、controller 层日志监听），拦截器更合适，另外拦截器还可以通过 HandlerMethod 获取方法上的注解，实现非常灵活的细粒度控制，这是 Filter 做不到的。

问题2：如何在拦截器中访问 Spring 配置文件中的属性（如白名单路径）？

答：有几种推荐方式，第一，通过构造器注入：在 Java Config 中将 @Value 配置传给拦截器实例；第二，在拦截器中通过 WebApplicationContextUtils.getRequiredWebApplicationContext(request.getServletContext()) 获取容器并 getBean，但不推荐，耦合高；第三，使用 @Component 注册拦截器，并在拦截器内部使用 @Value 注入属性。最优做法是在 WebMvcConfig 的 addInterceptors 方法中直接构造拦截器并传入 @Value 参数，这样避免拦截器作为 Bean 被其他组件误依赖，同时保持清晰的配置入口。

public void addInterceptors(InterceptorRegistry registry) {
    AuthInterceptor interceptor = new AuthInterceptor(whitelist);
    registry.addInterceptor(interceptor).addPathPatterns("/");
}

互动一下：你在实际项目中踩过拦截器执行顺序的坑吗？或者对拦截器与 AOP 的结合使用有独到心得？欢迎在评论区分享你的真实案例，一起讨论更好的实践方案！