Java 后端 / 系统课时

使用过滤器与拦截器

使用过滤器与拦截器

本课将把请求日志、链路标识和访问前置检查放到正确的位置:Filter 负责 Servlet 层的通用处理,HandlerInterceptor 负责 Spring MVC 处理器前后的业务检查,并通过一次请求验证完整执行顺序。

学习目标

  • 区分 Filter 与 HandlerInterceptor 的作用范围和调用时机
  • 使用 Filter 建立请求级链路上下文与耗时日志
  • 使用拦截器完成控制器调用前的访问检查

两类扩展点的位置

Filter 位于 Servlet 容器与 DispatcherServlet 之间,静态资源、异常派发和非 MVC 请求也可能经过它。拦截器位于 Spring MVC 内部,已经完成处理器映射,因此能知道即将执行哪个 Controller 方法。

Filter 与 HandlerInterceptor 请求链

典型顺序是:Filter 前置处理 → preHandle → Controller → postHandle → afterCompletion → Filter 后置处理。若 preHandle 返回 false,Controller 不会执行;但 Filter 的 finally 仍会运行。

选择职责边界

请求体包装、跨域、编码、链路 ID、通用审计等与 MVC 处理器无关的能力更适合 Filter。登录态检查、接口权限、处理器注解解析和控制器耗时统计更适合拦截器。

两者都不应承载复杂业务。Filter 无法直接获得最终 Controller 方法;拦截器也不覆盖脱离 Spring MVC 的请求。需要修改响应体时,通常应考虑 ResponseBodyAdvice,而不是在拦截器里强行改写。

实现请求上下文和前置检查

下面示例使用 OncePerRequestFilter 为每次请求生成或接收 X-Trace-Id,再用拦截器检查 X-Client-Id。通过 try/finally 清理 MDC,避免线程复用时污染下一次请求。

java
package com.example.requestchain;

import java.io.IOException;
import java.util.Map;
import java.util.UUID;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springframework.web.filter.OncePerRequestFilter;

@SpringBootApplication
public class RequestChainApplication {

    public static void main(String[] args) {
        SpringApplication.run(RequestChainApplication.class, args);
    }
}

@Component
class TraceFilter extends OncePerRequestFilter {

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

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain) throws ServletException, IOException {

        String traceId = request.getHeader("X-Trace-Id");
        if (traceId == null || traceId.isBlank()) {
            traceId = UUID.randomUUID().toString();
        }

        long startedAt = System.nanoTime();
        request.setAttribute("traceId", traceId);
        response.setHeader("X-Trace-Id", traceId);
        MDC.put("traceId", traceId);

        try {
            filterChain.doFilter(request, response);
        } finally {
            long elapsedMs = (System.nanoTime() - startedAt) / 1_000_000;
            log.info("{} {} -> {} ({} ms)",
                    request.getMethod(), request.getRequestURI(),
                    response.getStatus(), elapsedMs);
            MDC.remove("traceId");
        }
    }
}

@Component
class ClientAccessInterceptor implements HandlerInterceptor {

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

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

        String clientId = request.getHeader("X-Client-Id");
        if (clientId == null || clientId.isBlank()) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.setContentType("application/json");
            response.setCharacterEncoding("UTF-8");
            response.getWriter().write(
                    "{\"code\":\"MISSING_CLIENT_ID\",\"message\":\"缺少 X-Client-Id\"}");
            return false;
        }

        request.setAttribute("clientId", clientId);
        return true;
    }

    @Override
    public void afterCompletion(
            HttpServletRequest request,
            HttpServletResponse response,
            Object handler,
            Exception ex) {

        log.info("clientId={}, completed={}, exception={}",
                request.getAttribute("clientId"),
                response.getStatus(),
                ex == null ? "none" : ex.getClass().getSimpleName());
    }
}

@Configuration
class WebConfiguration implements WebMvcConfigurer {

    private final ClientAccessInterceptor clientAccessInterceptor;

    WebConfiguration(ClientAccessInterceptor clientAccessInterceptor) {
        this.clientAccessInterceptor = clientAccessInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(clientAccessInterceptor)
                .addPathPatterns("/api/**");
    }
}

@RestController
class ContextController {

    @GetMapping("/api/context")
    Map<String, Object> context(HttpServletRequest request) {
        return Map.of(
                "traceId", request.getAttribute("traceId"),
                "clientId", request.getAttribute("clientId"));
    }
}

预期输出

text
Tomcat started on port <PORT> (http)
Started RequestChainApplication in <TIME> seconds

实际端口、耗时和自动生成的链路 ID 每次可能不同。

验证拒绝与放行

不带客户端标识访问接口,拦截器会在 Controller 执行前终止请求。

bash
curl -i http://localhost:<PORT>/api/context

预期结果

text
HTTP/1.1 401
X-Trace-Id: <ID>

{"code":"MISSING_CLIENT_ID","message":"缺少 X-Client-Id"}

状态码应为 401,响应头中存在 X-Trace-Id,响应体由拦截器直接写出,因此不会进入 Controller。

带上 X-Client-Id 后,请求进入 Controller。

bash
curl -i -H "X-Client-Id: web-console" -H "X-Trace-Id: trace-demo" http://localhost:<PORT>/api/context

预期结果

text
HTTP/1.1 200
X-Trace-Id: trace-demo

{"traceId":"trace-demo","clientId":"web-console"}

控制台还会出现 Filter 的请求耗时日志和拦截器的完成日志。由于日志时间与耗时是动态值,实际内容会有所不同。

常见实现错误

不要在 Filter 或拦截器中保存可变的请求字段作为实例变量,因为这些组件默认是单例,会被多个线程并发访问。请求上下文应放在请求属性、MDC 或经过严格清理的 ThreadLocal 中。

postHandle 在响应已经由异常流程接管时不一定执行,清理动作更适合放在 afterCompletion 或 Filter 的 finally。如果访问检查需要读取 Controller 注解,可在 preHandle 中判断 handler 是否为 HandlerMethod 后再解析元数据。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用过滤器与拦截器

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通