Java 后端 / 系统课时
使用过滤器与拦截器
使用过滤器与拦截器
本课将把请求日志、链路标识和访问前置检查放到正确的位置:Filter 负责 Servlet 层的通用处理,HandlerInterceptor 负责 Spring MVC 处理器前后的业务检查,并通过一次请求验证完整执行顺序。
学习目标
- 区分 Filter 与 HandlerInterceptor 的作用范围和调用时机
- 使用 Filter 建立请求级链路上下文与耗时日志
- 使用拦截器完成控制器调用前的访问检查
两类扩展点的位置
Filter 位于 Servlet 容器与 DispatcherServlet 之间,静态资源、异常派发和非 MVC 请求也可能经过它。拦截器位于 Spring MVC 内部,已经完成处理器映射,因此能知道即将执行哪个 Controller 方法。

典型顺序是: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,避免线程复用时污染下一次请求。
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"));
}
}预期输出
Tomcat started on port <PORT> (http)
Started RequestChainApplication in <TIME> seconds实际端口、耗时和自动生成的链路 ID 每次可能不同。
验证拒绝与放行
不带客户端标识访问接口,拦截器会在 Controller 执行前终止请求。
curl -i http://localhost:<PORT>/api/context预期结果
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。
curl -i -H "X-Client-Id: web-console" -H "X-Trace-Id: trace-demo" http://localhost:<PORT>/api/context预期结果
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 后再解析元数据。