SpringBoot拦截器怎么用？从入门到多拦截器链式调用详解

前言

在现代的 spring boot 应用开发中，拦截器（interceptor）是一个非常重要的机制。

它位于客户端请求到达 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 可用于设置响应内容（如状态码、响应头、输出数据等）。

注意：prehandle、posthandle、aftercompletion 都由 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 方法完成注册和配置。

创建一个配置类，实现 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。

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

以上为个人经验，希望能给大家一个参考，也希望大家多多支持代码网。