前言

Spring Boot 里的拦截器，是现代应用开发中非常常见的一种机制。

简单来说，它位于客户端请求到达 Controller 之前，也参与响应返回之后的处理。

开发者可以在这个过程中插入自定义逻辑，实现对请求的预处理和后处理。这样一来，业务代码不用改，全局统一处理逻辑也能清晰落地。

拦截器的核心能力主要集中在三个方向：

• 请求预处理：身份认证、权限校验、日志记录、请求参数统一处理，这些活儿都能干。

• 响应后处理：对返回结果进行统一包装，或者清理一些临时资源。

• 异常处理和性能监控：统计接口调用耗时，捕获并处理异常信息，这些都不在话下。

在实际项目中，拦截器的应用场景非常广泛。

• 用户登录状态验证，拦截未登录用户访问受限接口

• 接口访问日志记录，方便审计和问题排查

• 请求参数校验和统一格式化

• 跨域请求处理和安全防护

• 性能监控和接口响应时间统计

本质上，就是在请求进入 Controller 前后，把通用且必要的逻辑统一收口，让代码维护更清爽。

1. 拦截器的核心接口与原理

在 Spring Boot 里，拦截器本质上是通过实现 Spring MVC 提供的 HandlerInterceptor 接口来完成的。

它允许我们在请求进入 Controller 前、请求处理后，以及请求完成后分别插入自定义逻辑。这个机制非常适合权限校验、日志记录、性能监控等场景。

拦截器的执行流程

 Client Request
       ↓
   preHandle()
       ↓        （如果返回 true）
   Controller   （调用 Service 层处理业务）
       ↓
  postHandle()
       ↓
    视图渲染
       ↓
afterCompletion()
       ↓
 Client Response

以上流程是一个简化示意，主要用于帮助理解拦截器的执行顺序。

实际底层还涉及 Servlet 容器对请求和响应的处理，以及 Spring MVC 内部的多层调用。不过核心脉络就是如此。

HandlerInterceptor接口的三个核心方法

/**
 * 在控制器方法执行前调用。
 * 可用于权限认证、参数校验、日志记录等。
 * 返回 false 会终止请求流程，后续的拦截器和 Controller 都不会被执行。
 */
boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler);

/**
 * 控制器方法执行后、视图渲染之前调用。
 * 可用于修改 ModelAndView，实现页面统一封装等功能。
 */
void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView);

/**
 * 请求处理完成后（视图渲染之后）调用。
 * 可用于资源清理、异常处理、日志收集等。
 */ 
void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex);

HttpServletRequest 可以获取请求相关信息，比如请求路径、参数、Header 等。

HttpServletResponse 则用于设置响应内容，比如状态码、响应头、输出数据等。

这三个方法都会由 Spring 框架在请求生命周期中自动调用。对业务代码来说，它们属于不可见的中间处理逻辑。

2. 示例：创建一个简单的拦截器

理论说完了，下面看一个实操示例。

创建一个类实现 HandlerInterceptor，并重写所需的方法。比如重写 preHandle，在请求到达 Controller 前打印日志：

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.web.servlet.HandlerInterceptor;

public class LoggingInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        System.out.println("请求URL：" + request.getRequestURI() + " | 方法：" + request.getMethod());
        // 返回 true 表示继续流程（放行），返回 false 则中断请求
        return true;
    }

    // 可根据需要重写 postHandle 和 afterCompletion 方法
}

通常登录拦截器会从请求头中获取 token。

解析后，再将用户信息存入 ThreadLocal，实现用户登录状态的维护与传递。

3. 示例：拦截器的注册与配置

拦截器类创建好之后，还需要注册到 Spring MVC 的拦截器链中，它才能生效。

实现方式是：通过实现 WebMvcConfigurer 接口的 addInterceptors 方法，完成注册和配置。

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new LoggingInterceptor())
                .addPathPatterns("/**")      // 拦截所有请求
                .excludePathPatterns("/login", "/register"); // 排除特定路径
    }
}

几个关键点：

• addPathPatterns 指定拦截的 URL 路径模式，支持通配符。

• excludePathPatterns 用来排除某些路径，比如登录页、静态资源等。

• 可以注册多个拦截器，按照添加顺序依次执行。

别忘了给 WebConfig 类加上 @Configuration 注解，Spring 框架才会识别并加载这个配置。

4. 多拦截器链式调用

真实项目中，通常不会只有一个拦截器。

多个拦截器会组成一个“拦截器链”。请求会依次经过每个拦截器的 preHandle、postHandle 和 afterCompletion 方法。

理解这个执行顺序，有助于合理设计拦截器的职责和调用时机。

执行顺序

假设按顺序注册了拦截器 A、B、C，执行顺序如下：

• 请求进入后，先按注册顺序依次调用各拦截器的 preHandle 方法：A → B → C

• 业务处理（Controller）执行

• 响应返回后，按注册顺序反向调用各拦截器的 postHandle 方法：C → B → A

• 请求完成后，按注册顺序反向调用各拦截器的 afterCompletion 方法：C → B → A

特殊情况说明

• 任何一个拦截器的 preHandle 返回 false，后续的拦截器和 Controller 都不会执行，请求会直接中断。

• afterCompletion 方法无论请求是否正常完成都会被调用，适合做资源清理。

示例代码（简化）

public class InterceptorA implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        System.out.println("A preHandle");
        return true;
    }
    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) {
        System.out.println("A postHandle");
    }
    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
        System.out.println("A afterCompletion");
    }
}
// InterceptorB 和 InterceptorC 类似

5. 拦截器与过滤器的区别

1. 作用层级不同

• 过滤器（Filter） 基于 Servlet 规范，属于 Servlet 容器层面的组件，能拦截所有到达应用的请求，包括静态资源和动态请求。

• 拦截器（Interceptor） 是 Spring MVC 的一部分，作用于 Spring 的 DispatcherServlet 之后，主要拦截控制器（Controller）的方法调用，只针对处理器映射的请求起作用。

2. 生命周期和调用时机

• 过滤器在请求进入应用时最早执行，可以在 Servlet 容器层对请求进行修改或阻断。

• 拦截器是在 Handler 执行之前和之后执行，能够访问 Handler 的具体信息，适合做业务相关的处理。

3. 功能侧重点

• 过滤器更适合做通用的请求过滤、编码设置、压缩、日志记录、安全检查等与底层协议相关的处理。

• 拦截器适合做业务层面的权限控制、日志记录、性能监控、参数绑定预处理等。

4. 配置方式

• 过滤器需要在 web.xml 中配置，或者通过代码注册（FilterRegistrationBean），相对底层。

• 拦截器通过实现 HandlerInterceptor 并注册到 Spring MVC 配置中，配置更简洁且与 Spring 框架集成紧密。

5. 是否支持异步处理

• 过滤器对异步请求的支持有限。

• 拦截器在 Spring MVC 中对异步请求支持更好，能够处理异步请求的生命周期。

简单总结：过滤器更偏底层、范围更广；拦截器偏 Spring MVC 层面，更加聚焦于业务处理。两者常结合使用，互为补充。

6. 总结

• 实现拦截器只需定义一个类实现 HandlerInterceptor 接口，并重写其中的方法，然后通过实现 WebMvcConfigurer 接口在 addInterceptors 方法中注册拦截器。

• 多个拦截器的调用顺序为：preHandle 方法按注册顺序执行，postHandle 和 afterCompletion 方法按注册顺序的反向执行。

• 过滤器是 Servlet 规范的一部分，运行于底层 Servlet 容器，作用范围更广；拦截器是 Spring MVC 特有，专注于处理请求和响应，能访问 Handler。

• 过滤器适合做通用功能（如日志、编码、安全等），拦截器适合做权限校验、请求处理和视图渲染前后操作，两者在实际项目中常常配合使用。