SpringBoot拦截器、过滤器、监听器区别与实战用法

SpringBoot拦截器、过滤器、监听器区别与实战用法

本文从 Servlet 规范底层原理出发，系统性地讲解 Filter（过滤器）、Interceptor（拦截器）、Listener（监听器）三者的核心区别、执行顺序、多种注册方式以及生产级实战用法。包含登录校验、权限控制、XSS防护、编码处理、性能监控、在线人数统计等 10+ 个完整可复用的代码案例。

目录

• 一、三者概述：一张图看懂区别
  • 1.1 核心概念速览
  • 1.2 三者在请求链路中的位置
  • 1.3 核心区别对比表
• 二、过滤器 Filter 详解与实战
  • 2.1 Filter 原理与生命周期
  • 2.2 注册方式一：@WebFilter + @ServletComponentScan
  • 2.3 注册方式二：FilterRegistrationBean（推荐）
  • 2.4 注册方式三：实现 Filter 接口 + @Component
  • 2.5 实战一：统一字符编码过滤器
  • 2.6 实战二：XSS 攻击防护过滤器
  • 2.7 实战三：SQL 注入防护过滤器
  • 2.8 实战四：请求体可重复读取过滤器（解决流只能读一次）
  • 2.9 实战五：请求日志过滤器（记录请求/响应详情）
  • 2.10 过滤器执行顺序控制
• 三、拦截器 Interceptor 详解与实战
  • 3.1 Interceptor 原理与生命周期
  • 3.2 实现方式：HandlerInterceptor 接口
  • 3.3 注册配置：WebMvcConfigurer
  • 3.4 实战一：登录状态校验拦截器
  • 3.5 实战二：接口权限校验拦截器（RBAC）
  • 3.6 实战三：接口性能监控拦截器
  • 3.7 实战四：接口防重复提交拦截器
  • 3.8 实战五：数据权限过滤拦截器（MyBatis 插件配合）
  • 3.9 拦截器排除路径与静态资源处理
  • 3.10 多个拦截器的执行顺序
• 四、监听器 Listener 详解与实战
  • 4.1 Listener 分类与原理
  • 4.2 注册方式：@WebListener + @ServletComponentScan
  • 4.3 注册方式二：ServletListenerRegistrationBean
  • 4.4 注册方式三：@Component 直接注册
  • 4.5 实战一：ServletContextListener 应用启动初始化
  • 4.6 实战二：HttpSessionListener 在线人数统计
  • 4.7 实战三：ServletRequestListener 请求计数与耗时统计
  • 4.8 实战四：HttpSessionAttributeListener 监听属性变化
  • 4.9 实战五：Spring 自定义事件与监听器（ApplicationEvent）
  • 4.10 实战六：Spring 异步事件监听（@Async + @EventListener）
• 五、三者执行顺序与嵌套关系深度解析
  • 5.1 请求进入时的完整执行链
  • 5.2 响应返回时的完整执行链
  • 5.3 异常发生时的执行链变化
  • 5.4 代码验证：打印完整执行顺序
• 六、常见问题与解法对比
  • 6.1 过滤器不生效的常见原因
  • 6.2 拦截器不生效的常见原因
  • 6.3 过滤器中无法注入 Bean 的问题
  • 6.4 拦截器中无法注入 Bean 的问题
  • 6.5 过滤器与拦截器如何选择
  • 6.6 静态资源被拦截的问题
  • 6.7 跨域配置用过滤器还是拦截器
  • 6.8 过滤器中读取请求体后 Controller 拿不到数据
• 七、生产级最佳实践
  • 7.1 三者职责划分原则
  • 7.2 性能优化建议
  • 7.3 安全加固建议
  • 7.4 可观测性建议
• 八、完整项目结构与代码汇总
  • 8.1 项目目录结构
  • 8.2 核心配置类完整代码
• 九、总结

一、三者概述：一张图看懂区别

1.1 核心概念速览

1.2 三者在请求链路中的位置

客户端请求
│
▼
┌─────────────────────────────────────────────┐
│ Tomcat / Jetty 容器 │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Filter1 │──▶│ Filter2 │──▶│ FilterN │ │ ← 过滤器链（Servlet 层）
│ └─────────┘ └─────────┘ └────┬────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │Dispatcher- │ │
│ │ Servlet │ │ ← Spring MVC 入口
│ └──────┬──────┘ │
│ │ │
│ ┌──────────▼────────┐│
│ │ Interceptor1 ││
│ │ preHandle() ││ ← 拦截器前置
│ └──────────┬────────┘│
│ │ │
│ ┌──────────▼────────┐│
│ │ Interceptor2 ││
│ │ preHandle() ││
│ └──────────┬────────┘│
│ │ │
│ ┌──────────▼────────┐│
│ │ Controller ││ ← 业务逻辑
│ │ Method ││
│ └──────────┬────────┘│
│ │ │
│ ┌──────────▼────────┐│
│ │ Interceptor2 ││
│ │ postHandle() ││ ← 拦截器后置
│ └──────────┬────────┘│
│ │ │
│ ┌──────────▼────────┐│
│ │ Interceptor1 ││
│ │ postHandle() ││
│ └──────────┬────────┘│
│ │ │
│ ┌──────▼──────┐ │
│ │ 视图渲染 │ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────────▼────────┐│
│ │ Interceptor2 ││
│ │ afterCompletion()││ ← 拦截器完成回调
│ └──────────┬────────┘│
│ ┌──────────▼────────┐│
│ │ Interceptor1 ││
│ │ afterCompletion()││
│ └──────────┬────────┘│
│ │ │
│ ┌─────────┐ ┌─────────┐ ┌────▼────┐ │
│ │ Filter1 │◀──│ Filter2 │◀──│ FilterN │ │ ← 过滤器链反向（响应）
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────┘
│
▼
客户端响应

1.3 核心区别对比表

二、过滤器 Filter 详解与实战

2.1 Filter 原理与生命周期

Filter 是 Servlet 规范定义的组件，在请求到达 Servlet 之前和响应离开 Servlet 之后执行。它基于责任链模式，多个 Filter 组成一条 FilterChain。

Filter 接口源码：

public interface Filter {

/**
* 容器启动时调用，只执行一次，用于初始化
*/
default void init(FilterConfig filterConfig) throws ServletException {
}

/**
* 每次请求被拦截时调用
* @param request 请求对象（ServletRequest）
* @param response 响应对象（ServletResponse）
* @param chain 过滤器链，调用 chain.doFilter() 将请求传递给下一个过滤器
*/
void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException;

/**
* 容器关闭时调用，只执行一次，用于销毁资源
*/
default void destroy() {
}
}

生命周期：

容器启动 → init()（仅一次）
│
▼
请求到达 → doFilter()（每次请求）
│
├── chain.doFilter() → 放行到下一个过滤器/目标资源
│
└── 不调用 chain.doFilter() → 中断请求，直接返回响应
│
▼
容器关闭 → destroy()（仅一次）

2.2 注册方式一：@WebFilter + @ServletComponentScan

这是最简洁的注册方式，适合简单场景。

第一步：在启动类上添加 @ServletComponentScan

@SpringBootApplication
@ServletComponentScan(basePackages = "com.example.filter")
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}

第二步：编写 Filter 并添加 @WebFilter 注解

package com.example.filter;

import lombok.extern.slf4j.Slf4j;
import javax.servlet.*;
import javax.servlet.annotation.WebFilter;
import javax.servlet.http.HttpServletRequest;
import java.io.IOException;

@Slf4j
@WebFilter(filterName = "myFilter", urlPatterns = "/*")
public class MyFilter implements Filter {

@Override
public void init(FilterConfig filterConfig) {
log.info("MyFilter 初始化");
}

@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {
HttpServletRequest httpRequest = (HttpServletRequest) request;
log.info("MyFilter 拦截请求：{}", httpRequest.getRequestURI());
long startTime = System.currentTimeMillis();

chain.doFilter(request, response);

long cost = System.currentTimeMillis() – startTime;
log.info("MyFilter 请求处理完成，耗时：{}ms", cost);
}

@Override
public void destroy() {
log.info("MyFilter 销毁");
}
}

注意：@WebFilter 注解本身不支持通过 @Order 控制执行顺序。如果需要控制顺序，必须使用 FilterRegistrationBean 方式。

2.3 注册方式二：FilterRegistrationBean（推荐）

这是生产环境推荐的注册方式，功能最强大，可以精确控制顺序、URL 模式、初始化参数等。

package com.example.config;

import com.example.filter.EncodingFilter;
import com.example.filter.XssFilter;
import com.example.filter.RequestLogFilter;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;

@Configuration
public class FilterConfig {

/**
* 注册编码过滤器，优先级最高
*/
@Bean
public FilterRegistrationBean<EncodingFilter> encodingFilterRegistration() {
FilterRegistrationBean<EncodingFilter> registration = new FilterRegistrationBean<>();
registration.setFilter(new EncodingFilter());
registration.addUrlPatterns("/*");
registration.setName("encodingFilter");
// 数字越小优先级越高
registration.setOrder(Ordered.HIGHEST_PRECEDENCE);
// 设置初始化参数
registration.addInitParameter("encoding", "UTF-8");
registration.addInitParameter("forceEncoding", "true");
return registration;
}

/**
* 注册 XSS 防护过滤器
*/
@Bean
public FilterRegistrationBean<XssFilter> xssFilterRegistration() {
FilterRegistrationBean<XssFilter> registration = new FilterRegistrationBean<>();
registration.setFilter(new XssFilter());
// 只拦截特定路径
registration.addUrlPatterns("/api/*");
registration.setName("xssFilter");
registration.setOrder(1);
return registration;
}

/**
* 注册请求日志过滤器
*/
@Bean
public FilterRegistrationBean<RequestLogFilter> requestLogFilterRegistration() {
FilterRegistrationBean<RequestLogFilter> registration = new FilterRegistrationBean<>();
registration.setFilter(new RequestLogFilter());
registration.addUrlPatterns("/*");
// 排除静态资源
registration.addInitParameter("exclusions", "/static/*,/public/*,*.js,*.css,*.png,*.jpg");
registration.setName("requestLogFilter");
registration.setOrder(2);
return registration;
}
}

2.4 注册方式三：实现 Filter 接口 + @Component

最简单的注册方式，直接加 @Component 注解即可被 Spring 管理。但这种方式默认拦截所有请求（/*），无法精确配置 URL 模式。

package com.example.filter;

import lombok.extern.slf4j.Slf4j;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import java.io.IOException;

@Slf4j
@Component
@Order(1) // 控制执行顺序，数字越小优先级越高
public class SimpleFilter implements Filter {

@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {
HttpServletRequest httpRequest = (HttpServletRequest) request;
log.info("SimpleFilter 拦截：{}", httpRequest.getRequestURI());
chain.doFilter(request, response);
}
}

三种注册方式对比：

2.5 实战一：统一字符编码过滤器

虽然 SpringBoot 已经提供了 CharacterEncodingFilter，但了解其实现原理有助于自定义编码处理。

package com.example.filter;

import lombok.extern.slf4j.Slf4j;
import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

/**
* 统一字符编码过滤器
*/
@Slf4j
public class EncodingFilter implements Filter {

private String encoding = "UTF-8";
private boolean forceEncoding = true;

@Override
public void init(FilterConfig filterConfig) {
String encodingParam = filterConfig.getInitParameter("encoding");
String forceParam = filterConfig.getInitParameter("forceEncoding");
if (encodingParam != null && !encodingParam.isEmpty()) {
this.encoding = encodingParam;
}
if (forceParam != null && !forceParam.isEmpty()) {
this.forceEncoding = Boolean.parseBoolean(forceParam);
}
log.info("EncodingFilter 初始化，编码：{}，强制编码：{}", encoding, forceEncoding);
}

@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {

HttpServletRequest httpRequest = (HttpServletRequest) request;
HttpServletResponse httpResponse = (HttpServletResponse) response;

// 设置请求编码
if (forceEncoding || request.getCharacterEncoding() == null) {
request.setCharacterEncoding(encoding);
}

// 设置响应编码
if (forceEncoding) {
response.setCharacterEncoding(encoding);
response.setContentType("text/html;charset=" + encoding);
}

log.debug("EncodingFilter 处理请求：{}，编码：{}", httpRequest.getRequestURI(), encoding);
chain.doFilter(request, response);
}

@Override
public void destroy() {
log.info("EncodingFilter 销毁");
}
}

SpringBoot 内置编码过滤器配置（更推荐）：

server:
servlet:
encoding:
charset: UTF–8
enabled: true
force: true

2.6 实战二：XSS 攻击防护过滤器

XSS（跨站脚本攻击）防护的核心思路是：对请求参数中的特殊字符进行转义，防止恶意脚本注入。

第一步：自定义 HttpServletRequestWrapper，重写获取参数的方法

package com.example.filter;

import org.apache.commons.text.StringEscapeUtils;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletRequestWrapper;
import java.util.*;

/**
* XSS 防护请求包装器
* 对所有请求参数进行 HTML 转义
*/
public class XssHttpServletRequestWrapper extends HttpServletRequestWrapper {

public XssHttpServletRequestWrapper(HttpServletRequest request) {
super(request);
}

/**
* 重写 getParameter，对单个参数值进行转义
*/
@Override
public String getParameter(String name) {
String value = super.getParameter(name);
return value == null ? null : escapeXss(value);
}

/**
* 重写 getParameterValues，对参数数组进行转义
*/
@Override
public String[] getParameterValues(String name) {
String[] values = super.getParameterValues(name);
if (values == null) {
return null;
}
String[] escapedValues = new String[values.length];
for (int i = 0; i < values.length; i++) {
escapedValues[i] = escapeXss(values[i]);
}
return escapedValues;
}

/**
* 重写 getParameterMap，对所有参数进行转义
*/
@Override
public Map<String, String[]> getParameterMap() {
Map<String, String[]> originalMap = super.getParameterMap();
if (originalMap == null || originalMap.isEmpty()) {
return originalMap;
}
Map<String, String[]> escapedMap = new LinkedHashMap<>();
for (Map.Entry<String, String[]> entry : originalMap.entrySet()) {
String[] values = entry.getValue();
if (values != null) {
String[] escapedValues = new String[values.length];
for (int i = 0; i < values.length; i++) {
escapedValues[i] = escapeXss(values[i]);
}
escapedMap.put(entry.getKey(), escapedValues);
} else {
escapedMap.put(entry.getKey(), null);
}
}
return escapedMap;
}

/**
* 重写 getHeader，对请求头进行转义
*/
@Override
public String getHeader(String name) {
String value = super.getHeader(name);
return value == null ? null : escapeXss(value);
}

/**
* XSS 转义方法
* 使用 Apache Commons Text 的 StringEscapeUtils
* 如果不想引入依赖，也可以手动实现
*/
private String escapeXss(String value) {
if (value == null || value.isEmpty()) {
return value;
}
// 方式一：使用 Apache Commons Text（推荐，更全面）
return StringEscapeUtils.escapeHtml4(value);

// 方式二：手动实现（不依赖第三方库）
// return manualEscape(value);
}

/**
* 手动 XSS 转义实现
*/
private String manualEscape(String value) {
StringBuilder sb = new StringBuilder(value.length() + 16);
for (int i = 0; i < value.length(); i++) {
char c = value.charAt(i);
switch (c) {
case '<':
sb.append("&lt;");
break;
case '>':
sb.append("&gt;");
break;
case '&':
sb.append("&amp;");
break;
case '"':
sb.append("&quot;");
break;
case '\\'':
sb.append("&#x27;");
break;
case '/':
sb.append("&#x2F;");
break;
default:
sb.append(c);
}
}
return sb.toString();
}
}

第二步：编写 XSS 过滤器

package com.example.filter;

import lombok.extern.slf4j.Slf4j;
import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;

/**
* XSS 攻击防护过滤器
*/
@Slf4j
public class XssFilter implements Filter {

/**
* 不需要 XSS 防护的路径（如文件上传接口）
*/
private static final List<String> EXCLUDE_PATHS = Arrays.asList(
"/api/file/upload",
"/api/import"
);

@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {

HttpServletRequest httpRequest = (HttpServletRequest) request;
String uri = httpRequest.getRequestURI();

// 排除不需要防护的路径
if (isExcludePath(uri)) {
chain.doFilter(request, response);
return;
}

// 使用包装后的 Request 传递给后续过滤器和 Controller
XssHttpServletRequestWrapper wrappedRequest = new XssHttpServletRequestWrapper(httpRequest);
chain.doFilter(wrappedRequest, response);
}

private boolean isExcludePath(String uri) {
return EXCLUDE_PATHS.stream().anyMatch(uri::startsWith);
}
}

注意：上面的 XSS 包装只处理了表单参数（getParameter 系列），对于 JSON 请求体（@RequestBody），需要额外处理。可以配合 ContentCachingRequestWrapper 或自定义 RequestWrapper 读取 InputStream 并转义后重新包装。

2.7 实战三：SQL 注入防护过滤器

SQL 注入防护的核心是检测请求参数中是否包含 SQL 关键字和特殊字符。

package com.example.filter;

import lombok.extern.slf4j.Slf4j;
import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.util.Enumeration;
import java.util.regex.Pattern;

/**
* SQL 注入防护过滤器
* 检测请求参数中是否包含 SQL 注入关键字
*/
@Slf4j
public class SqlInjectFilter implements Filter {

/**
* SQL 注入关键字正则
*/
private static final Pattern SQL_INJECT_PATTERN = Pattern.compile(
"(?:')|(?:–)|(/\\\\*(?:.|[\\\\n\\\\r])*?\\\\*/)|" +
"(\\\\b(select|update|and|or|delete|insert|truncate|char|into|" +
"substr|declare|exec|count|master|into|drop|execute|union|create|" +
"alter|grant|revoke|commit|rollback|savepoint|lock|unlock)\\\\b)",
Pattern.CASE_INSENSITIVE
);

@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {

HttpServletRequest httpRequest = (HttpServletRequest) request;
String uri = httpRequest.getRequestURI();

// 检查所有请求参数
Enumeration<String> parameterNames = httpRequest.getParameterNames();
while (parameterNames.hasMoreElements()) {
String paramName = parameterNames.nextElement();
String[] values = httpRequest.getParameterValues(paramName);
if (values == null) continue;

for (String value : values) {
if (value != null && SQL_INJECT_PATTERN.matcher(value).find()) {
log.warn("检测到 SQL 注入攻击，URI: {}，参数名: {}，参数值: {}",
uri, paramName, value);
// 拒绝请求
response.setContentType("application/json;charset=UTF-8");
response.getWriter().write("{\\"code\\":\\"40003\\",\\"message\\":\\"请求参数包含非法字符\\"}");
return;
}
}
}

chain.doFilter(request, response);
}
}

重要提示：SQL 注入防护的根本解决方案是使用预编译语句（PreparedStatement）和MyBatis 的 #{} 占位符，过滤器只能作为辅助防护手段。不要依赖过滤器作为唯一防护。

2.8 实战四：请求体可重复读取过滤器（解决流只能读一次）

在过滤器中读取请求体（如记录请求日志）后，Controller 中的 @RequestBody 会拿不到数据，因为 HttpServletRequest 的 InputStream 只能读一次。解决方案是自定义 HttpServletRequestWrapper，将请求体缓存到字节数组中。

第一步：可重复读取的 RequestWrapper

package com.example.filter;

import javax.servlet.ReadListener;
import javax.servlet.ServletInputStream;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletRequestWrapper;
import java.io.*;
import java.nio.charset.StandardCharsets;

/**
* 可重复读取请求体的 RequestWrapper
* 将请求体缓存到字节数组，实现多次读取
*/
public class CachedBodyHttpServletRequest extends HttpServletRequestWrapper {

/**
* 缓存的请求体字节数组
*/
private final byte[] cachedBody;

public CachedBodyHttpServletRequest(HttpServletRequest request) throws IOException {
super(request);
// 读取原始请求体并缓存
InputStream requestInputStream = request.getInputStream();
this.cachedBody = requestInputStream.readAllBytes();
}

/**
* 重写 getInputStream，返回基于缓存字节数组的输入流
*/
@Override
public ServletInputStream getInputStream() {
return new CachedBodyServletInputStream(this.cachedBody);
}

/**
* 重写 getReader，返回基于缓存字节数组的字符流
*/
@Override
public BufferedReader getReader() {
ByteArrayInputStream byteArrayInputStream = new ByteArrayInputStream(this.cachedBody);
return new BufferedReader(new InputStreamReader(byteArrayInputStream, StandardCharsets.UTF_8));
}

/**
* 获取缓存的请求体字符串
*/
public String getCachedBody() {
return new String(this.cachedBody, StandardCharsets.UTF_8);
}

/**
* 获取缓存的请求体字节数组
*/
public byte[] getCachedBodyBytes() {
return this.cachedBody;
}

/**
* 自定义 ServletInputStream，基于字节数组
*/
private static class CachedBodyServletInputStream extends ServletInputStream {

private final InputStream cachedBodyInputStream;

public CachedBodyServletInputStream(byte[] cachedBody) {
this.cachedBodyInputStream = new ByteArrayInputStream(cachedBody);
}

@Override
public boolean isFinished() {
try {
return cachedBodyInputStream.available() == 0;
} catch (IOException e) {
return true;
}
}

@Override
public boolean isReady() {
return true;
}

@Override
public void setReadListener(ReadListener readListener) {
throw new UnsupportedOperationException();
}

@Override
public int read() throws IOException {
return cachedBodyInputStream.read();
}

@Override
public int read(byte[] b, int off, int len) throws IOException {
return cachedBodyInputStream.read(b, off, len);
}
}
}

第二步：使用该 Wrapper 的过滤器

package com.example.filter;

import lombok.extern.slf4j.Slf4j;
import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import java.io.IOException;

/**
* 请求体缓存过滤器
* 确保请求体可以被多次读取（过滤器中读取后，Controller 仍能读取）
*/
@Slf4j
public class CachedBodyFilter implements Filter {

@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {

HttpServletRequest httpRequest = (HttpServletRequest) request;

// 只对 JSON 请求体进行包装（文件上传等不包装）
String contentType = httpRequest.getContentType();
if (contentType != null && contentType.contains("application/json")) {
CachedBodyHttpServletRequest cachedRequest = new CachedBodyHttpServletRequest(httpRequest);
chain.doFilter(cachedRequest, response);
} else {
chain.doFilter(request, response);
}
}
}

2.9 实战五：请求日志过滤器（记录请求/响应详情）

生产环境中，记录完整的请求和响应日志对于排查问题至关重要。

package com.example.filter;

import com.example.filter.CachedBodyHttpServletRequest;
import lombok.extern.slf4j.Slf4j;
import org.springframework.util.StopWatch;
import org.springframework.web.util.ContentCachingResponseWrapper;
import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.Map;

/**
* 请求日志过滤器
* 记录请求 URL、方法、参数、请求体、响应体、耗时等完整信息
*/
@Slf4j
public class RequestLogFilter implements Filter {

/**
* 最大记录的请求体长度（避免大文件日志爆炸）
*/
private static final int MAX_BODY_LENGTH = 2048;

/**
* 不记录日志的路径前缀
*/
private static final String[] EXCLUDE_PREFIXES = {
"/static", "/public", "/webjars", "/swagger", "/v2/api-docs", "/v3/api-docs"
};

/**
* 不记录日志的文件后缀
*/
private static final String[] EXCLUDE_SUFFIXES = {
".js", ".css", ".png", ".jpg", ".jpeg", ".gif", ".ico", ".woff", ".woff2", ".ttf"
};

@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {

HttpServletRequest httpRequest = (HttpServletRequest) request;
HttpServletResponse httpResponse = (HttpServletResponse) response;

String uri = httpRequest.getRequestURI();

// 排除不需要记录日志的请求
if (shouldSkipLog(uri)) {
chain.doFilter(request, response);
return;
}

StopWatch stopWatch = new StopWatch();
stopWatch.start();

// 包装请求和响应，以便读取请求体和响应体
CachedBodyHttpServletRequest cachedRequest = new CachedBodyHttpServletRequest(httpRequest);
ContentCachingResponseWrapper cachedResponse = new ContentCachingResponseWrapper(httpResponse);

try {
// 记录请求日志
logRequest(cachedRequest);

// 执行请求
chain.doFilter(cachedRequest, cachedResponse);

} finally {
stopWatch.stop();

// 记录响应日志
logResponse(cachedRequest, cachedResponse, stopWatch.getTotalTimeMillis());

// 必须将响应体写回原始响应，否则客户端收不到数据
cachedResponse.copyBodyToResponse();
}
}

/**
* 记录请求日志
*/
private void logRequest(CachedBodyHttpServletRequest request) {
StringBuilder sb = new StringBuilder();
sb.append("\\n========== 请求开始 ==========\\n");
sb.append("URL: ").append(request.getRequestURL()).append("\\n");
sb.append("Method: ").append(request.getMethod()).append("\\n");
sb.append("URI: ").append(request.getRequestURI()).append("\\n");
sb.append("QueryString: ").append(request.getQueryString()).append("\\n");
sb.append("RemoteAddr: ").append(request.getRemoteAddr()).append("\\n");
sb.append("ContentType: ").append(request.getContentType()).append("\\n");

// 记录请求头
sb.append("Headers: \\n");
Enumeration<String> headerNames = request.getHeaderNames();
while (headerNames.hasMoreElements()) {
String headerName = headerNames.nextElement();
// 敏感头不记录
if (!"authorization".equalsIgnoreCase(headerName) && !"cookie".equalsIgnoreCase(headerName)) {
sb.append(" ").append(headerName).append(": ").append(request.getHeader(headerName)).append("\\n");
}
}

// 记录请求参数（表单）
Map<String, String[]> parameterMap = request.getParameterMap();
if (parameterMap != null && !parameterMap.isEmpty()) {
sb.append("Parameters: \\n");
parameterMap.forEach((key, value) ->
sb.append(" ").append(key).append(": ").append(String.join(",", value)).append("\\n"));
}

// 记录请求体（JSON）
String body = request.getCachedBody();
if (body != null && !body.isEmpty()) {
if (body.length() > MAX_BODY_LENGTH) {
body = body.substring(0, MAX_BODY_LENGTH) + "…(truncated)";
}
sb.append("Body: ").append(body).append("\\n");
}

sb.append("========== 请求结束 ==========");
log.info(sb.toString());
}

/**
* 记录响应日志
*/
private void logResponse(HttpServletRequest request, ContentCachingResponseWrapper response, long cost) {
StringBuilder sb = new StringBuilder();
sb.append("\\n========== 响应开始 ==========\\n");
sb.append("URI: ").append(request.getRequestURI()).append("\\n");
sb.append("Status: ").append(response.getStatus()).append("\\n");
sb.append("Cost: ").append(cost).append("ms\\n");

// 记录响应体
byte[] content = response.getContentAsByteArray();
if (content.length > 0) {
String responseBody = new String(content, StandardCharsets.UTF_8);
if (responseBody.length() > MAX_BODY_LENGTH) {
responseBody = responseBody.substring(0, MAX_BODY_LENGTH) + "…(truncated)";
}
sb.append("ResponseBody: ").append(responseBody).append("\\n");
}

sb.append("========== 响应结束 ==========");
log.info(sb.toString());
}

/**
* 判断是否跳过日志记录
*/
private boolean shouldSkipLog(String uri) {
for (String prefix : EXCLUDE_PREFIXES) {
if (uri.startsWith(prefix)) {
return true;
}
}
for (String suffix : EXCLUDE_SUFFIXES) {
if (uri.endsWith(suffix)) {
return true;
}
}
return false;
}
}

2.10 过滤器执行顺序控制

使用 FilterRegistrationBean 控制顺序（推荐）：

@Configuration
public class FilterConfig {

@Bean
public FilterRegistrationBean<Filter1> filter1Registration() {
FilterRegistrationBean<Filter1> registration = new FilterRegistrationBean<>();
registration.setFilter(new Filter1());
registration.addUrlPatterns("/*");
registration.setOrder(1); // 数字越小，优先级越高
return registration;
}

@Bean
public FilterRegistrationBean<Filter2> filter2Registration() {
FilterRegistrationBean<Filter2> registration = new FilterRegistrationBean<>();
registration.setFilter(new Filter2());
registration.addUrlPatterns("/*");
registration.setOrder(2);
return registration;
}
}

执行顺序验证：

请求进入 → Filter1.doFilter() 前置 → Filter2.doFilter() 前置 → Controller
↓
响应返回 ← Filter1.doFilter() 后置 ← Filter2.doFilter() 后置 ← 视图渲染

注意：@WebFilter 注解的过滤器执行顺序按类名字母顺序排列，不可控。如果需要精确控制顺序，必须使用 FilterRegistrationBean。

三、拦截器 Interceptor 详解与实战

3.1 Interceptor 原理与生命周期

拦截器是 Spring MVC 提供的组件，在 DispatcherServlet 内部执行，用于在 Controller 方法执行前后进行处理。

HandlerInterceptor 接口源码：

public interface HandlerInterceptor {

/**
* 在 Controller 方法执行之前调用
* @return true 继续执行（下一个拦截器或 Controller）；false 中断请求
*/
default boolean preHandle(HttpServletRequest request, HttpServletResponse response,
Object handler) throws Exception {
return true;
}

/**
* 在 Controller 方法执行之后、视图渲染之前调用
* 可以修改 ModelAndView
*/
default void postHandle(HttpServletRequest request, HttpServletResponse response,
Object handler, ModelAndView modelAndView) throws Exception {
}

/**
* 在整个请求完成之后（视图渲染结束）调用
* 通常用于资源清理
* 只有 preHandle 返回 true 的拦截器才会执行此方法
*/
default void afterCompletion(HttpServletRequest request, HttpServletResponse response,
Object handler, Exception ex) throws Exception {
}
}

生命周期与执行时机：

DispatcherServlet.doDispatch()
│
├── 1. 获取 Handler（Controller 方法）
│
├── 2. 执行拦截器链的 preHandle()
│ ├── Interceptor1.preHandle() → true
│ ├── Interceptor2.preHandle() → true
│ └── … 全部返回 true 才继续
│ （如果某个返回 false，执行已通过拦截器的 afterCompletion，然后返回）
│
├── 3. 执行 Controller 方法（ha.handle()）
│
├── 4. 执行拦截器链的 postHandle()（倒序）
│ ├── Interceptor2.postHandle()
│ └── Interceptor1.postHandle()
│
├── 5. 渲染视图（processDispatchResult）
│
└── 6. 执行拦截器链的 afterCompletion()（倒序）
├── Interceptor2.afterCompletion()
└── Interceptor1.afterCompletion()

3.2 实现方式：HandlerInterceptor 接口

package com.example.interceptor;

import lombok.extern.slf4j.Slf4j;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.ModelAndView;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

/**
* 自定义拦截器示例
*/
@Slf4j
public class MyInterceptor implements HandlerInterceptor {

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
Object handler) throws Exception {
log.info("MyInterceptor preHandle – 请求路径: {}", request.getRequestURI());

// handler 通常是 HandlerMethod 对象，可以获取 Controller 方法信息
if (handler instanceof org.springframework.web.method.HandlerMethod) {
org.springframework.web.method.HandlerMethod handlerMethod =
(org.springframework.web.method.HandlerMethod) handler;
log.info("Controller 类: {}", handlerMethod.getBeanType().getSimpleName());
log.info("Controller 方法: {}", handlerMethod.getMethod().getName());
}

// 返回 true 继续执行，返回 false 中断请求
return true;
}

@Override
public void postHandle(HttpServletRequest request, HttpServletResponse response,
Object handler, ModelAndView modelAndView) throws Exception {
log.info("MyInterceptor postHandle – 请求路径: {}", request.getRequestURI());
// 可以修改 ModelAndView，如添加公共数据
if (modelAndView != null) {
modelAndView.addObject("serverTime", System.currentTimeMillis());
}
}

@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
Object handler, Exception ex) throws Exception {
log.info("MyInterceptor afterCompletion – 请求路径: {}", request.getRequestURI());
if (ex != null) {
log.error("请求处理发生异常", ex);
}
// 资源清理，如移除 ThreadLocal 中的数据
}
}

3.3 注册配置：WebMvcConfigurer

package com.example.config;

import com.example.interceptor.LoginInterceptor;
import com.example.interceptor.PerformanceInterceptor;
import com.example.interceptor.PermissionInterceptor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
* Web MVC 配置类
* 注册拦截器、配置静态资源、跨域等
*/
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

@Autowired
private LoginInterceptor loginInterceptor;

@Autowired
private PermissionInterceptor permissionInterceptor;

@Autowired
private PerformanceInterceptor performanceInterceptor;

@Override
public void addInterceptors(InterceptorRegistry registry) {

// 注册性能监控拦截器，优先级最高（最先执行 preHandle，最后执行 postHandle/afterCompletion）
registry.addInterceptor(performanceInterceptor)
.addPathPatterns("/**")
.excludePathPatterns("/static/**", "/public/**")
.order(0);

// 注册登录校验拦截器
registry.addInterceptor(loginInterceptor)
.addPathPatterns("/api/**") // 拦截所有 /api 开头的请求
.excludePathPatterns( // 排除不需要登录的路径
"/api/user/login",
"/api/user/register",
"/api/user/sendCode",
"/api/doc/**"
)
.order(1);

// 注册权限校验拦截器
registry.addInterceptor(permissionInterceptor)
.addPathPatterns("/api/admin/**") // 只拦截管理员接口
.order(2);
}
}

路径匹配规则：

• ? 匹配一个字符
• * 匹配零个或多个字符（单层路径）
• ** 匹配零个或多个目录（多层路径）
• 示例：/api/** 匹配 /api/user、/api/user/1、/api/order/list 等

3.4 实战一：登录状态校验拦截器

package com.example.interceptor;

import com.example.common.context.UserContext;
import com.example.common.context.UserInfo;
import com.example.common.result.Result;
import com.example.common.result.ResultCode;
import com.example.util.JwtUtils;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

/**
* 登录状态校验拦截器
* 校验请求头中的 Token，解析用户信息并存入 ThreadLocal
*/
@Slf4j
@Component
public class LoginInterceptor implements HandlerInterceptor {

@Autowired
private JwtUtils jwtUtils;

private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
Object handler) throws Exception {

// 1. 从请求头获取 Token
String token = request.getHeader("Authorization");
if (token != null && token.startsWith("Bearer ")) {
token = token.substring(7);
}

// 2. Token 为空，返回未登录
if (token == null || token.isEmpty()) {
writeUnauthorizedResponse(response, "未登录或登录已过期");
return false;
}

// 3. 校验 Token 有效性
if (!jwtUtils.validateToken(token)) {
writeUnauthorizedResponse(response, "Token无效或已过期");
return false;
}

// 4. 解析用户信息
UserInfo userInfo = jwtUtils.parseToken(token);
if (userInfo == null) {
writeUnauthorizedResponse(response, "Token解析失败");
return false;
}

// 5. 将用户信息存入 ThreadLocal，供后续业务使用
UserContext.setUser(userInfo);
log.info("用户登录校验通过，userId: {}, userName: {}", userInfo.getUserId(), userInfo.getUserName());

return true;
}

@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
Object handler, Exception ex) {
// 必须清理 ThreadLocal，防止内存泄漏
UserContext.clear();
}

/**
* 写入未登录响应
*/
private void writeUnauthorizedResponse(HttpServletResponse response, String message) throws Exception {
response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
response.setContentType("application/json;charset=UTF-8");
Result<Void> result = Result.fail(ResultCode.UNAUTHORIZED.getCode(), message);
response.getWriter().write(OBJECT_MAPPER.writeValueAsString(result));
}
}

UserContext 工具类：

package com.example.common.context;

/**
* 用户上下文，基于 ThreadLocal 存储当前登录用户信息
*/
public class UserContext {

private static final ThreadLocal<UserInfo> USER_THREAD_LOCAL = new ThreadLocal<>();

public static void setUser(UserInfo userInfo) {
USER_THREAD_LOCAL.set(userInfo);
}

public static UserInfo getUser() {
return USER_THREAD_LOCAL.get();
}

public static Long getUserId() {
UserInfo user = USER_THREAD_LOCAL.get();
return user != null ? user.getUserId() : null;
}

public static void clear() {
USER_THREAD_LOCAL.remove();
}
}

3.5 实战二：接口权限校验拦截器（RBAC）

基于自定义注解 + 拦截器实现细粒度的接口权限控制。

第一步：定义权限注解

package com.example.common.annotation;

import java.lang.annotation.*;

/**
* 接口权限校验注解
* 标注在 Controller 方法上，指定访问该接口所需的权限
*/
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequirePermission {

/**
* 所需权限标识（如 "user:list", "user:delete"）
*/
String[] value();

/**
* 权限校验逻辑：AND（全部拥有）/ OR（拥有其一）
*/
Logical logical() default Logical.AND;

enum Logical {
AND, OR
}
}

第二步：权限校验拦截器

package com.example.interceptor;

import com.example.common.annotation.RequirePermission;
import com.example.common.context.UserContext;
import com.example.common.context.UserInfo;
import com.example.common.result.Result;
import com.example.common.result.ResultCode;
import com.example.service.PermissionService;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.Arrays;
import java.util.Set;

/**
* 接口权限校验拦截器
* 基于 @RequirePermission 注解进行 RBAC 权限校验
*/
@Slf4j
@Component
public class PermissionInterceptor implements HandlerInterceptor {

@Autowired
private PermissionService permissionService;

private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
Object handler) throws Exception {

// 只处理 HandlerMethod（Controller 方法），静态资源等不处理
if (!(handler instanceof HandlerMethod)) {
return true;
}

HandlerMethod handlerMethod = (HandlerMethod) handler;

// 1. 先检查类上的注解
RequirePermission classAnnotation = handlerMethod.getBeanType().getAnnotation(RequirePermission.class);
// 2. 再检查方法上的注解（方法上的注解优先级更高）
RequirePermission methodAnnotation = handlerMethod.getMethodAnnotation(RequirePermission.class);

// 没有权限注解，放行
if (classAnnotation == null && methodAnnotation == null) {
return true;
}

// 方法上的注解覆盖类上的注解
RequirePermission annotation = methodAnnotation != null ? methodAnnotation : classAnnotation;

// 3. 获取当前登录用户
UserInfo userInfo = UserContext.getUser();
if (userInfo == null) {
writeForbiddenResponse(response, "未登录");
return false;
}

// 4. 获取用户拥有的权限列表
Set<String> userPermissions = permissionService.getUserPermissions(userInfo.getUserId());

// 5. 校验权限
String[] requiredPermissions = annotation.value();
boolean hasPermission;

if (annotation.logical() == RequirePermission.Logical.AND) {
// AND：必须拥有全部权限
hasPermission = userPermissions.containsAll(Arrays.asList(requiredPermissions));
} else {
// OR：拥有任一权限即可
hasPermission = Arrays.stream(requiredPermissions).anyMatch(userPermissions::contains);
}

if (!hasPermission) {
log.warn("用户无权限访问，userId: {}, 所需权限: {}, 拥有权限: {}",
userInfo.getUserId(), Arrays.toString(requiredPermissions), userPermissions);
writeForbiddenResponse(response, "权限不足，无法访问该接口");
return false;
}

return true;
}

private void writeForbiddenResponse(HttpServletResponse response, String message) throws Exception {
response.setStatus(HttpServletResponse.SC_FORBIDDEN);
response.setContentType("application/json;charset=UTF-8");
Result<Void> result = Result.fail(ResultCode.PERMISSION_DENIED.getCode(), message);
response.getWriter().write(OBJECT_MAPPER.writeValueAsString(result));
}
}

使用示例：

@RestController
@RequestMapping("/api/admin/user")
@RequirePermission("user:manage") // 类级别，所有方法都需要 user:manage 权限
public class UserAdminController {

@GetMapping("/list")
@RequirePermission("user:list") // 方法级别，需要 user:list 权限
public Result<PageResult<UserVO>> list() {
// …
}

@PostMapping("/delete")
@RequirePermission(value = {"user:delete", "user:manage"}, logical = RequirePermission.Logical.OR)
public Result<Void> delete(@RequestParam Long id) {
// …
}
}

3.6 实战三：接口性能监控拦截器

package com.example.interceptor;

import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.ModelAndView;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.time.Duration;

/**
* 接口性能监控拦截器
* 记录每个接口的执行耗时，慢接口告警，Micrometer 指标埋点
*/
@Slf4j
@Component
public class PerformanceInterceptor implements HandlerInterceptor {

/**
* 慢接口阈值（毫秒）
*/
private static final long SLOW_API_THRESHOLD = 3000;

private static final String START_TIME_ATTR = "performance_start_time";

@Autowired
private MeterRegistry meterRegistry;

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
Object handler) {
// 记录开始时间
request.setAttribute(START_TIME_ATTR, System.currentTimeMillis());
return true;
}

@Override
public void postHandle(HttpServletRequest request, HttpServletResponse response,
Object handler, ModelAndView modelAndView) {
// 可以在这里记录 Controller 方法执行耗时（不含视图渲染）
}

@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
Object handler, Exception ex) {
Long startTime = (Long) request.getAttribute(START_TIME_ATTR);
if (startTime == null) {
return;
}

long cost = System.currentTimeMillis() – startTime;
String uri = request.getRequestURI();
String method = request.getMethod();
int status = response.getStatus();

// 1. 记录耗时日志
if (cost > SLOW_API_THRESHOLD) {
log.warn("慢接口告警，URI: {}，Method: {}，Status: {}，耗时: {}ms（超过阈值 {}ms）",
uri, method, status, cost, SLOW_API_THRESHOLD);
} else {
log.debug("接口耗时，URI: {}，Method: {}，Status: {}，耗时: {}ms",
uri, method, status, cost);
}

// 2. Micrometer 指标埋点
if (handler instanceof HandlerMethod) {
HandlerMethod handlerMethod = (HandlerMethod) handler;
String className = handlerMethod.getBeanType().getSimpleName();
String methodName = handlerMethod.getMethod().getName();

Timer.builder("api.request.duration")
.description("接口请求耗时")
.tag("uri", uri)
.tag("method", method)
.tag("class", className)
.tag("methodName", methodName)
.tag("status", String.valueOf(status))
.register(meterRegistry)
.record(Duration.ofMillis(cost));
}
}
}

3.7 实战四：接口防重复提交拦截器

基于 Redis + 自定义注解实现接口防重复提交。

第一步：防重复提交注解

package com.example.common.annotation;

import java.lang.annotation.*;
import java.util.concurrent.TimeUnit;

/**
* 防重复提交注解
* 标注在 Controller 方法上，指定时间内不允许重复提交
*/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RepeatSubmit {

/**
* 间隔时间（默认 5 秒）
*/
int interval() default 5;

/**
* 时间单位
*/
TimeUnit timeUnit() default TimeUnit.SECONDS;

/**
* 提示信息
*/
String message() default "请勿重复提交";
}

第二步：防重复提交拦截器

package com.example.interceptor;

import com.example.common.annotation.RepeatSubmit;
import com.example.common.context.UserContext;
import com.example.common.result.Result;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.concurrent.TimeUnit;

/**
* 防重复提交拦截器
* 基于 Redis 实现，同一用户同一接口在指定时间内只能提交一次
*/
@Slf4j
@Component
public class RepeatSubmitInterceptor implements HandlerInterceptor {

@Autowired
private StringRedisTemplate redisTemplate;

private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();

private static final String REPEAT_SUBMIT_KEY_PREFIX = "repeat_submit:";

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
Object handler) throws Exception {

if (!(handler instanceof HandlerMethod)) {
return true;
}

HandlerMethod handlerMethod = (HandlerMethod) handler;
RepeatSubmit annotation = handlerMethod.getMethodAnnotation(RepeatSubmit.class);

// 没有防重复提交注解，放行
if (annotation == null) {
return true;
}

// 1. 构建唯一标识：用户ID + 请求URI + 请求方法
Long userId = UserContext.getUserId();
String userKey = userId != null ? String.valueOf(userId) : request.getRemoteAddr();
String redisKey = REPEAT_SUBMIT_KEY_PREFIX + userKey + ":" +
request.getRequestURI() + ":" + request.getMethod();

// 2. 尝试设置 key（setIfAbsent 等价于 SETNX）
int interval = annotation.interval();
TimeUnit timeUnit = annotation.timeUnit();
Boolean success = redisTemplate.opsForValue().setIfAbsent(redisKey, "1", interval, timeUnit);

// 3. 如果 key 已存在，说明重复提交
if (Boolean.FALSE.equals(success)) {
log.warn("重复提交拦截，userId: {}, URI: {}, 间隔: {}{}",
userKey, request.getRequestURI(), interval, timeUnit);
writeRepeatSubmitResponse(response, annotation.message());
return false;
}

return true;
}

private void writeRepeatSubmitResponse(HttpServletResponse response, String message) throws Exception {
response.setStatus(HttpServletResponse.SC_OK);
response.setContentType("application/json;charset=UTF-8");
Result<Void> result = Result.fail("40006", message);
response.getWriter().write(OBJECT_MAPPER.writeValueAsString(result));
}
}

使用示例：

@PostMapping("/order/create")
@RepeatSubmit(interval = 3, message = "订单正在处理中，请勿重复提交")
public Result<OrderVO> createOrder(@RequestBody @Valid OrderCreateDTO dto) {
// 业务逻辑
}

3.8 实战五：数据权限过滤拦截器（MyBatis 插件配合）

数据权限是指不同用户只能看到自己权限范围内的数据（如部门经理只能看到本部门数据）。

第一步：数据权限注解

package com.example.common.annotation;

import java.lang.annotation.*;

/**
* 数据权限注解
* 标注在 Controller 方法或 Mapper 方法上，指定数据权限过滤规则
*/
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface DataScope {

/**
* 部门表别名（SQL 中部门 ID 所在表的别名）
*/
String deptAlias() default "d";

/**
* 用户表别名（SQL 中用户 ID 所在表的别名）
*/
String userAlias() default "u";

/**
* 是否过滤本人数据
*/
boolean self() default true;
}

第二步：数据权限拦截器（将数据权限信息存入 ThreadLocal）

package com.example.interceptor;

import com.example.common.annotation.DataScope;
import com.example.common.context.DataScopeContext;
import com.example.common.context.DataScopeInfo;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

/**
* 数据权限拦截器
* 读取 Controller 方法上的 @DataScope 注解，将数据权限信息存入 ThreadLocal，
* 供 MyBatis 插件读取并动态拼接 SQL 条件
*/
@Slf4j
@Component
public class DataScopeInterceptor implements HandlerInterceptor {

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
Object handler) {

if (!(handler instanceof HandlerMethod)) {
return true;
}

HandlerMethod handlerMethod = (HandlerMethod) handler;

// 优先取方法上的注解，其次取类上的注解
DataScope methodAnnotation = handlerMethod.getMethodAnnotation(DataScope.class);
DataScope classAnnotation = handlerMethod.getBeanType().getAnnotation(DataScope.class);
DataScope annotation = methodAnnotation != null ? methodAnnotation : classAnnotation;

if (annotation != null) {
DataScopeInfo info = new DataScopeInfo();
info.setDeptAlias(annotation.deptAlias());
info.setUserAlias(annotation.userAlias());
info.setSelf(annotation.self());
DataScopeContext.set(info);
log.debug("数据权限拦截器设置数据权限，deptAlias: {}, userAlias: {}",
annotation.deptAlias(), annotation.userAlias());
}

return true;
}

@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
Object handler, Exception ex) {
// 清理 ThreadLocal
DataScopeContext.clear();
}
}

第三步：MyBatis 插件（读取 ThreadLocal 中的数据权限，拼接 SQL）

package com.example.plugin;

import com.example.common.context.DataScopeContext;
import com.example.common.context.DataScopeInfo;
import com.example.common.context.UserContext;
import com.example.common.context.UserInfo;
import lombok.extern.slf4j.Slf4j;
import org.apache.ibatis.executor.statement.StatementHandler;
import org.apache.ibatis.mapping.BoundSql;
import org.apache.ibatis.mapping.MappedStatement;
import org.apache.ibatis.plugin.*;
import org.apache.ibatis.reflection.MetaObject;
import org.apache.ibatis.reflection.SystemMetaObject;
import org.springframework.stereotype.Component;
import java.sql.Connection;
import java.util.Properties;

/**
* 数据权限 MyBatis 插件
* 在 SQL 执行前，根据数据权限信息动态拼接 WHERE 条件
*/
@Slf4j
@Component
@Intercepts({
@Signature(type = StatementHandler.class, method = "prepare",
args = {Connection.class, Integer.class})
})
public class DataScopeInterceptor implements Interceptor {

@Override
public Object intercept(Invocation invocation) throws Throwable {
DataScopeInfo dataScope = DataScopeContext.get();
if (dataScope == null) {
return invocation.proceed();
}

UserInfo currentUser = UserContext.getUser();
if (currentUser == null) {
return invocation.proceed();
}

// 获取 StatementHandler 和 SQL
StatementHandler statementHandler = (StatementHandler) invocation.getTarget();
MetaObject metaObject = SystemMetaObject.forObject(statementHandler);
MappedStatement mappedStatement = (MappedStatement) metaObject.getValue("delegate.mappedStatement");
BoundSql boundSql = statementHandler.getBoundSql();
String originalSql = boundSql.getSql();

// 构建数据权限 SQL 条件
String dataScopeSql = buildDataScopeSql(dataScope, currentUser);

if (dataScopeSql != null && !dataScopeSql.isEmpty()) {
// 将数据权限条件拼接到原 SQL 中
String newSql = "SELECT * FROM (" + originalSql + ") temp_data_scope WHERE " + dataScopeSql;
metaObject.setValue("delegate.boundSql.sql", newSql);
log.debug("数据权限 SQL 拼接完成，原SQL: {}，新SQL: {}", originalSql, newSql);
}

return invocation.proceed();
}

/**
* 构建数据权限 SQL 条件
* 实际项目中应根据用户的数据权限范围（全部/本部门/本部门及以下/本人）来构建
*/
private String buildDataScopeSql(DataScopeInfo dataScope, UserInfo user) {
// 简化示例：只看本人数据
// 实际项目应根据用户角色和数据权限范围来构建
if (dataScope.isSelf()) {
return dataScope.getUserAlias() + ".user_id = " + user.getUserId();
}
return null;
}

@Override
public Object plugin(Object target) {
return Plugin.wrap(target, this);
}

@Override
public void setProperties(Properties properties) {
}
}

3.9 拦截器排除路径与静态资源处理

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(loginInterceptor)
.addPathPatterns("/**")
.excludePathPatterns(
// 静态资源
"/static/**",
"/public/**",
"/resources/**",
"/META-INF/resources/**",
// 常用静态资源后缀
"/**/*.js",
"/**/*.css",
"/**/*.png",
"/**/*.jpg",
"/**/*.jpeg",
"/**/*.gif",
"/**/*.ico",
"/**/*.woff",
"/**/*.woff2",
"/**/*.ttf",
"/**/*.svg",
// Swagger / Knife4j
"/swagger-ui.html",
"/swagger-ui/**",
"/swagger-resources/**",
"/v2/api-docs",
"/v3/api-docs",
"/webjars/**",
"/doc.html",
// 健康检查
"/actuator/**",
// 错误页面
"/error"
);
}

/**
* 配置静态资源映射（如果关闭了默认静态资源映射）
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/static/**")
.addResourceLocations("classpath:/static/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}

3.10 多个拦截器的执行顺序

假设有三个拦截器，注册顺序为 Interceptor1（order=1）、Interceptor2（order=2）、Interceptor3（order=3）：

请求进入
│
▼
Interceptor1.preHandle() → true
│
▼
Interceptor2.preHandle() → true
│
▼
Interceptor3.preHandle() → true
│
▼
Controller 方法执行
│
▼
Interceptor3.postHandle()
│
▼
Interceptor2.postHandle()
│
▼
Interceptor1.postHandle()
│
▼
视图渲染
│
▼
Interceptor3.afterCompletion()
│
▼
Interceptor2.afterCompletion()
│
▼
Interceptor1.afterCompletion()
│
▼
响应返回

关键规则：

• preHandle 按注册顺序（order 从小到大）正序执行
• postHandle 和 afterCompletion 按注册顺序倒序执行
• 如果某个拦截器的 preHandle 返回 false，则只有它之前（已执行 preHandle）的拦截器的 afterCompletion 会被执行

四、监听器 Listener 详解与实战

4.1 Listener 分类与原理

监听器是基于观察者模式的组件，用于监听 Servlet 容器中特定事件的发生。

Servlet 规范中的监听器分类：

三大域对象对比：