侧边栏壁纸
博主头像
洋洋的技术笔记

行动起来,活在当下

  • 累计撰写 20 篇文章
  • 累计创建 2 个标签
  • 累计收到 0 条评论

目 录CONTENT

文章目录

Spring Boot拦截器与过滤器实战

洋洋的技术笔记
2026-11-17 / 0 评论 / 0 点赞 / 3 阅读 / 0 字

Spring Boot拦截器与过滤器实战

Filter 与 HandlerInterceptor 都能处理请求横切逻辑,但它们的位置、职责和异常边界并不相同。真正可靠的方案,不是把所有逻辑都塞进某一层,而是让每个组件在正确的位置做正确的事。

上一篇《Spring Boot参数校验与自定义校验》解决了无效输入如何尽早被发现的问题。本文继续向请求链路外侧移动,梳理 Servlet Filter 与 Spring MVC HandlerInterceptor 的执行顺序,并通过请求追踪、访问检查、耗时统计和异常处理,构建一套清晰的 Web 请求处理流程。

环境说明:示例基于 Spring Boot 3.x、Spring Framework 6、Java 17 和 Servlet Web 应用,使用 jakarta.servlet.*。Spring Boot 2.x 对应 javax.servlet.*。本文不适用于 Spring WebFlux;响应式应用应使用 WebFilter 等另一套 API。


一、先看清完整请求链路

在典型 Spring MVC 请求中,可以先把调用过程简化为:

客户端
  │
  ▼
Servlet 容器
  │
  ▼
Filter 1 → Filter 2
  │
  ▼
DispatcherServlet
  │
  ▼
HandlerInterceptor.preHandle
  │
  ▼
Controller
  │
  ▼
HandlerInterceptor.postHandle
  │
  ▼
视图渲染(如果需要)
  │
  ▼
HandlerInterceptor.afterCompletion
  │
  ▼
Filter 回程
  │
  ▼
客户端收到响应

过滤器属于 Servlet 规范,在 DispatcherServlet 之外执行。它可以处理所有进入容器的请求,包括静态资源、错误分发以及不被 Spring MVC 处理的请求。

拦截器属于 Spring MVC,在已经确定处理器后执行。它能获得 handler 信息,更适合处理与 Controller 调用相关的逻辑。

这个区别决定了基本分工:

  • 请求追踪、编码、通用耗时统计、安全响应头:优先考虑 Filter;

  • 登录状态检查、接口权限、Controller 前置条件:可以考虑 HandlerInterceptor;

  • 参数格式与业务规则:交给 Bean Validation 和 Service;

  • Controller 业务异常转换:交给 @RestControllerAdvice;

  • 完整认证授权体系:优先使用 Spring Security,而不是重复手写安全框架。


二、Filter 的基本写法

先实现一个最小过滤器,记录请求方法和 URI:

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

@Component
public class RequestLogFilter extends OncePerRequestFilter {

    private static final Logger log = LoggerFactory.getLogger(RequestLogFilter.class);

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain
    ) throws ServletException, IOException {
        log.info("收到请求:{} {}", request.getMethod(), request.getRequestURI());
        filterChain.doFilter(request, response);
    }
}

OncePerRequestFilter 是 Spring 提供的过滤器基类,目标是让一次请求只执行一次过滤逻辑,并提供请求分派相关的控制入口。

最重要的是这一句:

filterChain.doFilter(request, response);

它表示继续调用后续过滤器和目标资源。没有调用它,请求就会停留在当前过滤器。除非是有意短路,否则不要忘记继续传递请求。

这里的“除非”不能省略:访问检查失败时,我们会有意不调用 doFilter,直接写出 401 或 403 响应。

为什么不直接实现 Filter

也可以直接实现 jakarta.servlet.Filter:

@Component
public class SimpleFilter implements Filter {

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

Filter 更通用,但 OncePerRequestFilter 已经把请求和响应转换为 HTTP 类型,并提供单次执行及分派控制,日常 Spring MVC 开发通常更方便。


三、过滤器注册与重复执行问题

3.1 使用 @Component

上面的 RequestLogFilter 使用 @Component,Spring Boot 会把它注册到 Servlet 过滤链中。这种方式简单,适合规则明确的通用过滤器。

如果需要精确控制 URL、顺序和初始化参数,可以使用 FilterRegistrationBean:

import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class FilterConfig {

    @Bean
    FilterRegistrationBean<RequestLogFilter> requestLogFilter() {
        RequestLogFilter filter = new RequestLogFilter();

        FilterRegistrationBean<RequestLogFilter> registration =
                new FilterRegistrationBean<>(filter);
        registration.addUrlPatterns("/api/*");
        registration.setOrder(100);
        return registration;
    }
}

此时不要再给 RequestLogFilter 添加 @Component。否则它可能既作为普通 Bean 被自动注册,又通过 FilterRegistrationBean 注册一次,造成日志、响应头或业务逻辑重复执行。

3.2 两种注册方式如何选择

方式

适合场景

注意事项

@Component

全站通用过滤逻辑

注意与其他注册方式重复

FilterRegistrationBean

精确 URL、顺序和参数

同一个过滤器不要重复注册

OncePerRequestFilter 子类

Spring Web 请求处理

仍需检查异步与错误分派需求

如果线上出现“一次请求打印两次追踪日志”,首先检查是否存在重复注册,而不是立即怀疑框架执行顺序。


四、实战一:使用 Filter 实现请求追踪

在《Spring Boot统一异常处理方案》中,错误响应已经包含 traceId。现在把这个字段真正接入请求链路和日志。

4.1 生成并清理 MDC

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.UUID;
import java.util.regex.Pattern;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.web.filter.OncePerRequestFilter;

public class TraceIdFilter extends OncePerRequestFilter {

    public static final String TRACE_ID = "traceId";
    public static final String HEADER = "X-Trace-Id";

    private static final Pattern SAFE_TRACE_ID =
            Pattern.compile("[A-Za-z0-9_-]{8,64}");
    private static final Logger log =
            LoggerFactory.getLogger(TraceIdFilter.class);

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain
    ) throws ServletException, IOException {
        String traceId = resolveTraceId(request);
        long startedAt = System.nanoTime();

        try {
            MDC.put(TRACE_ID, traceId);
            response.setHeader(HEADER, traceId);
            filterChain.doFilter(request, response);
        } finally {
            long elapsedMillis = (System.nanoTime() - startedAt) / 1_000_000;
            log.info("请求结束:{} {},状态 {},耗时 {} ms",
                    request.getMethod(),
                    request.getRequestURI(),
                    response.getStatus(),
                    elapsedMillis);
            MDC.remove(TRACE_ID);
        }
    }

    private String resolveTraceId(HttpServletRequest request) {
        String incoming = request.getHeader(HEADER);
        if (incoming != null && SAFE_TRACE_ID.matcher(incoming).matches()) {
            return incoming;
        }
        return UUID.randomUUID().toString().replace("-", "");
    }
}

这段代码完成了四件事:

  1. 接收合法的上游追踪 ID,否则生成新的 ID;

  2. 放入 SLF4J MDC,让后续日志共享同一标识;

  3. 写入响应头,方便客户端和网关排查;

  4. 在 finally 中记录结束日志并清理 MDC。

MDC 通常基于线程上下文。请求处理线程会被池化复用,如果不在 finally 中清理,下一个请求可能读到上一个请求的追踪 ID。

4.2 注册追踪过滤器

@Configuration
public class FilterConfig {

    @Bean
    FilterRegistrationBean<TraceIdFilter> traceIdFilter() {
        FilterRegistrationBean<TraceIdFilter> registration =
                new FilterRegistrationBean<>(new TraceIdFilter());
        registration.addUrlPatterns("/*");
        registration.setOrder(Ordered.HIGHEST_PRECEDENCE + 10);
        return registration;
    }
}

需要补充导入:

import org.springframework.core.Ordered;

把追踪过滤器放在较靠前位置,后续组件才能尽早使用 traceId。但安全框架已有自己的过滤链顺序,接入 Spring Security 时应结合实际链路和现有追踪方案确定位置,而不是机械追求“永远第一”。

4.3 在日志中输出追踪 ID

logging:
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] [%X{traceId:-}] %logger{36} - %msg%n"

统一异常处理器中可以直接读取:

String traceId = MDC.get(TraceIdFilter.TRACE_ID);

如果项目已经使用 Micrometer Tracing、OpenTelemetry 或 SkyWalking,应复用现有追踪体系,不要同时维护多套互不关联的 ID。


五、HandlerInterceptor 的三个核心方法

拦截器实现 HandlerInterceptor 接口:

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.ModelAndView;

@Component
public class ApiInterceptor implements HandlerInterceptor {

    private static final Logger log = LoggerFactory.getLogger(ApiInterceptor.class);

    @Override
    public boolean preHandle(
            HttpServletRequest request,
            HttpServletResponse response,
            Object handler
    ) {
        log.info("Controller 调用前:{}", handler);
        return true;
    }

    @Override
    public void postHandle(
            HttpServletRequest request,
            HttpServletResponse response,
            Object handler,
            ModelAndView modelAndView
    ) {
        log.info("Controller 调用完成");
    }

    @Override
    public void afterCompletion(
            HttpServletRequest request,
            HttpServletResponse response,
            Object handler,
            Exception ex
    ) {
        if (ex != null) {
            log.warn("请求处理存在异常", ex);
        }
    }
}

三个方法不能简单理解为“前、中、后”三个无差别钩子。

5.1 preHandle

在目标 Handler 执行前调用。返回 true 继续,返回 false 中断后续处理。

适合检查登录状态、接口访问条件或写入 MVC 层需要的请求属性。

5.2 postHandle

在 Handler 已执行、视图渲染前调用。对于返回 HTML 的 MVC 页面,它可以补充 ModelAndView。

对于 @RestController,响应体通常已经在 Handler 执行阶段完成转换,postHandle 不应被当作通用的响应体修改器。

5.3 afterCompletion

在请求完成阶段调用,适合清理资源和记录最终结果。ex 可能为空,使用前必须判断。

不要在 afterCompletion 中依赖 postHandle 一定执行过。出现异常或前置短路时,正常后处理路径会不同。


六、注册拦截器与路径排除

通过 WebMvcConfigurer 注册:

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 WebMvcConfig implements WebMvcConfigurer {

    private final ApiInterceptor apiInterceptor;

    public WebMvcConfig(ApiInterceptor apiInterceptor) {
        this.apiInterceptor = apiInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(apiInterceptor)
                .addPathPatterns("/api/**")
                .excludePathPatterns(
                        "/api/auth/login",
                        "/api/health",
                        "/error"
                )
                .order(100);
    }
}

推荐只拦截明确需要的 /api/,而不是默认使用 /。后者容易把静态资源、文档、健康检查和错误页也卷入业务逻辑。

路径排除应遵循两个原则:

  • 登录、验证码等公开入口不能被自己的登录检查挡住;

  • /error 等内部分发路径需要明确是否参与,避免异常处理再次进入业务拦截。

修改路径后,应分别验证正常请求、排除路径和不存在路径,不要只看一个成功接口。


七、实战二:在拦截器中进行访问检查

下面用一个简化的 API 访问令牌演示 preHandle 如何短路。它仅用于内部服务或教学示例,不等同于完整认证授权方案。

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import org.slf4j.MDC;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;

@Component
public class ApiAccessInterceptor implements HandlerInterceptor {

    private final ApiAccessProperties properties;

    public ApiAccessInterceptor(ApiAccessProperties properties) {
        this.properties = properties;
    }

    @Override
    public boolean preHandle(
            HttpServletRequest request,
            HttpServletResponse response,
            Object handler
    ) throws IOException {
        String token = request.getHeader("X-Api-Token");
        if (properties.token().equals(token)) {
            return true;
        }

        writeUnauthorized(request, response);
        return false;
    }

    private void writeUnauthorized(
            HttpServletRequest request,
            HttpServletResponse response
    ) throws IOException {
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
        response.setCharacterEncoding(StandardCharsets.UTF_8.name());
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);

        String traceId = MDC.get(TraceIdFilter.TRACE_ID);
        String body = """
                {"status":401,"code":"UNAUTHORIZED",\
                "message":"访问令牌无效",\
                "path":"%s","traceId":"%s"}
                """.formatted(request.getRequestURI(), traceId);
        response.getWriter().write(body);
    }
}

配置属性使用不可变对象承载:

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "app.api-access")
public record ApiAccessProperties(String token) {
}

在配置类或启动类上启用:

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableConfigurationProperties(ApiAccessProperties.class)
public class ApiAccessConfig {
}

本地环境示例:

app:
  api-access:
    token: ${API_ACCESS_TOKEN:local-dev-token}

生产环境应通过安全的配置注入方式提供真实凭据,并采用成熟认证机制。不要把长期有效的令牌提交到仓库,也不要把上面的简单比较当作 Spring Security 的替代品。

为什么直接写响应,而不是抛出业务异常

这里是访问检查失败后的主动短路,目标是立即返回稳定的 401 JSON。Filter 位于 DispatcherServlet 外部,其中抛出的异常肯定不能依赖 @RestControllerAdvice 按 Controller 业务异常处理。

拦截器不同执行阶段的异常解析路径也不完全一致。不要未经验证就假设所有异常都会进入同一个全局处理器。主动短路时直接写出语义明确的响应,行为更容易预测。


八、多个过滤器和拦截器的执行顺序

假设注册了两个过滤器 F1、F2,以及两个拦截器 I1、I2,顺序均为 1、2:

F1 前置
  → F2 前置
    → I1.preHandle
      → I2.preHandle
        → Controller
      → I2.postHandle
    → I1.postHandle
    → I2.afterCompletion
  → I1.afterCompletion
  → F2 回程
→ F1 回程

整体上呈现“先进后出”的嵌套结构。拦截器注册可以设置顺序:

registry.addInterceptor(traceContextInterceptor)
        .addPathPatterns("/api/**")
        .order(1);

registry.addInterceptor(apiAccessInterceptor)
        .addPathPatterns("/api/**")
        .order(2);

不过,顺序不是越精细越好。真正重要的是依赖关系:

  • 追踪上下文必须先于需要它的日志和访问检查;

  • 认证必须先于依赖用户身份的权限判断;

  • 资源清理必须覆盖成功和异常路径。

如果某个组件依赖另一个组件设置的请求属性,应在代码注释、配置和测试中明确这个前提。


九、统一异常处理的边界

统一异常处理与本文的请求链路应当协同,而不是互相替代。

9.1 Controller 业务异常

@GetMapping("/api/users/{id}")
public UserResponse getUser(@PathVariable Long id) {
    return userService.getById(id);
}

userService.getById 抛出业务异常后,可以由 @RestControllerAdvice 转换为统一错误结构。

9.2 Filter 异常

Filter 在 DispatcherServlet 外执行。如果自己完成编码、解压缩或请求包装时失败,应记录正确日志,并使用容器错误机制或明确的错误响应。

不要简单写成:

// 不推荐:假设 Controller Advice 一定会接住 Filter 异常
throw new BusinessException("请求失败");

9.3 拦截器主动短路

访问失败时直接返回 401、403 等响应,通常比把业务异常抛到不确定的处理路径更清晰。

9.4 不要重复写错误响应

如果容器或 Spring MVC 已经生成了标准错误响应,Filter 不应在 finally 中无条件再写一段 JSON。重复写入可能破坏响应状态,甚至出现“响应已提交”的异常。

可以用以下信息辅助判断:

if (response.isCommitted()) {
    log.warn("响应已经提交,不再修改响应体");
}

isCommitted 只表示响应是否已经提交,不代表请求是否成功。日志和清理逻辑仍需根据真实状态处理。


十、请求耗时统计应该放在哪一层

如果关心整个 Servlet 请求耗时,Filter 更合适,因为它覆盖 DispatcherServlet 外侧的处理时间。

前文的 TraceIdFilter 已展示基本写法:

long startedAt = System.nanoTime();
try {
    filterChain.doFilter(request, response);
} finally {
    long elapsedMillis = (System.nanoTime() - startedAt) / 1_000_000;
    log.info("请求耗时:{} ms", elapsedMillis);
}

如果关心 Controller 执行前后的 MVC 阶段,可以在拦截器中设置请求属性:

@Override
public boolean preHandle(
        HttpServletRequest request,
        HttpServletResponse response,
        Object handler
) {
    request.setAttribute("mvcStartedAt", System.nanoTime());
    return true;
}

@Override
public void afterCompletion(
        HttpServletRequest request,
        HttpServletResponse response,
        Object handler,
        Exception ex
) {
    Long startedAt = (Long) request.getAttribute("mvcStartedAt");
    if (startedAt != null) {
        long elapsedMillis = (System.nanoTime() - startedAt) / 1_000_000;
        log.info("MVC 阶段耗时:{} ms", elapsedMillis);
    }
}

使用 System.nanoTime() 计算耗时,不要依赖可能受系统时钟校准影响的当前时间。

生产环境还应把指标接入统一监控系统。每个请求都打印 Info 日志,在高并发场景下可能产生过量日志,可按慢请求阈值或采样策略输出。


十一、读取请求体与响应体的注意事项

有些场景希望在 Filter 中记录请求体,但 Servlet 输入流通常只能读取一次。直接调用:

String body = new String(
        request.getInputStream().readAllBytes(),
        StandardCharsets.UTF_8
);

可能导致后续 Controller 无法读取 @RequestBody。

Spring 提供的包装器可以缓解部分问题:

import org.springframework.web.util.ContentCachingRequestWrapper;
import org.springframework.web.util.ContentCachingResponseWrapper;

ContentCachingRequestWrapper requestWrapper =
        new ContentCachingRequestWrapper(request);
ContentCachingResponseWrapper responseWrapper =
        new ContentCachingResponseWrapper(response);

try {
    filterChain.doFilter(requestWrapper, responseWrapper);
} finally {
    byte[] requestBody = requestWrapper.getContentAsByteArray();
    byte[] responseBody = responseWrapper.getContentAsByteArray();
    responseWrapper.copyBodyToResponse();
}

这里仍有几个重要边界:

  • 请求缓存通常在下游真正读取请求体后才有内容;

  • 大文件、大 JSON 不应无限制缓存到内存;

  • 密码、令牌、身份证号等敏感字段不能原样写日志;

  • 使用响应包装器后,要在合适阶段调用 copyBodyToResponse,否则客户端可能收不到原响应体;

  • 流式响应、压缩和异步场景需要单独验证。

如果只是为了定位问题,优先记录路径、状态、耗时和追踪 ID,不要默认记录完整报文。


十二、异步、错误分派与静态资源

OncePerRequestFilter 的名字不意味着可以忽略所有分派细节。异步请求、错误转发和容器分发方式可能影响是否再次进入过滤器。

可以检查并覆盖相关方法:

@Override
protected boolean shouldNotFilterAsyncDispatch() {
    return true;
}

@Override
protected boolean shouldNotFilterErrorDispatch() {
    return true;
}

这里的返回值应根据业务需求决定,不要机械复制。若追踪上下文必须覆盖异步分派,就需要评估清理时机和线程上下文传播,而不是简单跳过。

对于明显不需要处理的静态资源,也可以跳过:

@Override
protected boolean shouldNotFilter(
        HttpServletRequest request
) {
    String path = request.getRequestURI();
    return path.startsWith("/assets/")
            || path.equals("/favicon.ico");
}

路径判断应使用应用真实结构。若部署时存在上下文路径,不要只凭浏览器地址硬编码假设。

MDC 基于线程上下文,而异步处理可能切换线程。需要完整分布式追踪时,应使用支持上下文传播的追踪组件,不要只依赖手动 MDC.put 覆盖全部场景。


十三、组合成一套可维护的配置

下面把组件职责整理为一套推荐结构:

TraceIdFilter
  - 生成或接收追踪 ID
  - 设置响应头与 MDC
  - 统计整个请求耗时
  - finally 清理 MDC

ApiAccessInterceptor
  - 仅处理指定 /api/** 路径
  - 检查内部 API 访问令牌
  - 失败时直接返回统一风格的 401 JSON

Controller
  - 接收已校验参数
  - 调用业务 Service

@RestControllerAdvice
  - 处理 Controller 与业务调用链异常
  - 生成包含 traceId 的统一错误响应

配置只保留清晰的注册关系:

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Bean
    FilterRegistrationBean<TraceIdFilter> traceIdFilter() {
        FilterRegistrationBean<TraceIdFilter> registration =
                new FilterRegistrationBean<>(new TraceIdFilter());
        registration.addUrlPatterns("/*");
        registration.setOrder(Ordered.HIGHEST_PRECEDENCE + 10);
        return registration;
    }

    @Bean
    WebMvcConfigurer apiInterceptorConfigurer(
            ApiAccessInterceptor apiAccessInterceptor
    ) {
        return new WebMvcConfigurer() {
            @Override
            public void addInterceptors(InterceptorRegistry registry) {
                registry.addInterceptor(apiAccessInterceptor)
                        .addPathPatterns("/api/**")
                        .excludePathPatterns(
                                "/api/auth/login",
                                "/api/health",
                                "/error"
                        )
                        .order(100);
            }
        };
    }
}

一个配置类中也可以直接同时实现两种注册,但不要把所有业务逻辑都堆进 WebConfig。配置负责组装,具体行为放在独立组件中。

参数校验则继续负责入口数据约束。这样,追踪、访问控制、参数校验、业务处理和异常转换各有位置。


十四、使用 MockMvc 验证关键路径

仅启动项目没有报错,不能证明过滤器与拦截器按预期工作。至少应覆盖公开路径、拒绝访问、正常访问和异常响应。

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;

import static org.hamcrest.Matchers.notNullValue;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@SpringBootTest
@AutoConfigureMockMvc
class ApiAccessIntegrationTest {

    @Autowired
    MockMvc mockMvc;

    @Test
    void publicHealthEndpointShouldBeAccessible() throws Exception {
        mockMvc.perform(get("/api/health"))
                .andExpect(status().isOk())
                .andExpect(header().exists(TraceIdFilter.HEADER));
    }

    @Test
    void protectedEndpointShouldRejectMissingToken() throws Exception {
        mockMvc.perform(get("/api/users/1"))
                .andExpect(status().isUnauthorized())
                .andExpect(jsonPath("$.code").value("UNAUTHORIZED"))
                .andExpect(jsonPath("$.traceId", notNullValue()));
    }

    @Test
    void protectedEndpointShouldAcceptValidToken() throws Exception {
        mockMvc.perform(get("/api/users/1")
                        .header("X-Api-Token", "local-dev-token"))
                .andExpect(status().isOk())
                .andExpect(header().exists(TraceIdFilter.HEADER));
    }
}

如果用户不存在时正常业务约定返回 404,最后一个测试就应改用真实存在的测试数据或单独准备一个测试端点,不要为了通过测试把 404 改成 200。

还可以补充:

  • 同一请求的日志和错误响应使用同一 traceId;

  • 上游 ID 合法时保留,非法时替换;

  • 一个请求只注册一次过滤器;

  • 静态资源不进入业务访问检查;

  • Controller 业务异常仍由统一异常处理器转换。


十五、Filter、拦截器与 Spring Security 如何选择

需求

推荐位置

原因

请求追踪 ID

Filter 或现有追踪组件

覆盖完整 Servlet 请求链路

通用耗时统计

Filter

能包含 MVC 外侧处理时间

简单 MVC 前置检查

HandlerInterceptor

接近 Controller,路径配置直观

Controller 业务权限

Spring Security 或业务授权层

规则复杂,需要成熟安全上下文

参数格式校验

Bean Validation

声明式约束,错误处理统一

业务状态与业务权限

Service / 授权组件

与具体业务对象和规则相关

Controller 异常响应

@RestControllerAdvice

统一错误结构与 HTTP 语义

响应式 WebFilter

WebFlux 的 WebFilter

Servlet API 不适用于 WebFlux

微服务网关过滤

Gateway GlobalFilter

位于网关请求链路,不是 MVC 拦截器

当一个需求同时可以通过 Filter 和拦截器实现时,先问两个问题:

  1. 是否必须覆盖 DispatcherServlet 之外的请求?

  2. 是否依赖 Spring MVC 的 Handler 信息和路径语义?

第一个问题偏向 Filter,第二个问题偏向拦截器。认证授权涉及完整安全体系时,则优先评估 Spring Security。


十六、常见问题自查

问题

推荐处理

过滤器执行两次

检查 @Component 与 FilterRegistrationBean 是否重复注册

请求没有进入 Controller

检查是否遗漏 filterChain.doFilter,或拦截器返回了 false

后续日志出现其他请求 ID

在 finally 中清理 MDC,并检查异步上下文传播

上游传入异常追踪 ID

限制字符集和长度,非法值重新生成

登录接口也被拦截

将公开入口加入 excludePathPatterns

静态资源也执行权限检查

缩小到 /api/**,不要默认拦截全部路径

Filter 异常没有统一 JSON

Filter 在 DispatcherServlet 外,单独处理错误边界

postHandle 修改 JSON 不生效

REST 响应转换时机不同,不把它当通用响应体修改器

afterCompletion 中空指针

对 ex、请求属性和其他可空值进行判断

Controller 读不到请求体

检查 Filter 是否提前消费输入流,合理使用缓存包装器

客户端收不到响应体

使用响应缓存包装器后调用 copyBodyToResponse

日志泄露敏感数据

不记录完整令牌、密码和隐私字段,必要时脱敏

异步请求追踪断裂

检查线程切换、分派策略和追踪上下文传播

用简单令牌代替完整安全体系

仅限简单内部场景,生产认证授权优先 Spring Security


十七、总结

Filter 与 HandlerInterceptor 的价值,在于把横切逻辑从业务代码中分离出来:

  1. Filter 位于 Servlet 层,覆盖 DispatcherServlet 外侧的请求链路。

  2. HandlerInterceptor 位于 Spring MVC 层,适合 Controller 相关的前置检查与完成处理。

  3. OncePerRequestFilter 提供 HTTP 化和单次执行基础,但仍需考虑异步与错误分派。

  4. @Component 与 FilterRegistrationBean 不应造成同一过滤器重复注册。

  5. 请求追踪应生成合法 ID、写入 MDC 和响应头,并在 finally 中清理。

  6. preHandle 返回 false 可以短路,主动短路时应写出明确的错误响应。

  7. 多个组件的执行顺序应服务于依赖关系,而不是随意设置数字。

  8. Controller 异常可交给统一异常处理器,Filter 异常需要单独设计边界。

  9. 请求体与响应体缓存存在内存、流和敏感信息风险,不应默认记录完整报文。

  10. 复杂认证授权优先 Spring Security,响应式与网关场景使用各自的过滤机制。

下一站预告

下一篇《Spring Boot跨域处理方案》将介绍同源策略、预检请求、CORS 配置与凭据限制,并分析跨域配置与过滤器、拦截器及 Spring Security 同时存在时的常见冲突。


作者:洋洋技术笔记 发布日期:2026-11-16 系列:Spring Boot实战 - 第9篇


原文链接:洋洋的技术笔记

0

评论区