《Spring Boot 入门》11.3 拦截器与过滤器

2026-10-09T15:43:10.001+08:00  INFO 43496 --- [nio-8080-exec-1] c.e.library.filter.TraceFilter            : [filter] before /api/books
2026-10-09T15:43:10.002+08:00  INFO 43496 --- [nio-8080-exec-1] c.e.l.interceptor.TraceInterceptor        : [interceptor] preHandle /api/books
2026-10-09T15:43:10.003+08:00  INFO 43496 --- [nio-8080-exec-1] c.e.library.web.BookController            : [controller] list
2026-10-09T15:43:10.005+08:00  INFO 43496 --- [nio-8080-exec-1] c.e.l.interceptor.TraceInterceptor        : [interceptor] postHandle /api/books
2026-10-09T15:43:10.006+08:00  INFO 43496 --- [nio-8080-exec-1] c.e.l.interceptor.TraceInterceptor        : [interceptor] afterCompletion /api/books
2026-10-09T15:43:10.007+08:00  INFO 43496 --- [nio-8080-exec-1] c.e.library.filter.TraceFilter            : [filter] after /api/books

@Configuration
public class FilterConfig {

    @Bean
    public FilterRegistrationBean<TraceFilter> traceFilterRegistration(TraceFilter filter) {
        FilterRegistrationBean<TraceFilter> registration = new FilterRegistrationBean<>(filter);
        registration.addUrlPatterns("/*");
        registration.setOrder(Ordered.HIGHEST_PRECEDENCE);
        registration.setName("traceFilter");
        return registration;
    }
}

@Configuration
public class WebConfig implements WebMvcConfigurer {

    private final AuthInterceptor authInterceptor;

    public WebConfig(AuthInterceptor authInterceptor) {
        this.authInterceptor = authInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(authInterceptor)
                .addPathPatterns("/api/**")                 // 只拦 API
                .excludePathPatterns(                       // 排除登录与公开接口
                        "/api/auth/login",
                        "/api/auth/register",
                        "/api/public/**");
    }
}

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.MDC;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

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

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class RequestIdFilter extends OncePerRequestFilter {

    public static final String MDC_KEY = "requestId";
    public static final String HEADER = "X-Request-Id";

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        String requestId = request.getHeader(HEADER);
        if (requestId == null || requestId.isBlank()) {
            requestId = UUID.randomUUID().toString().replace("-", "").substring(0, 16);
        }
        MDC.put(MDC_KEY, requestId);
        response.setHeader(HEADER, requestId);   // 回写，方便前端/网关串联

        long start = System.currentTimeMillis();
        try {
            chain.doFilter(request, response);
        } finally {
            long cost = System.currentTimeMillis() - start;
            log.info("{} {} -> {} ({} ms)",
                    request.getMethod(), request.getRequestURI(),
                    response.getStatus(), cost);
            MDC.remove(MDC_KEY);   // 必须清理，线程池复用否则会串号
        }
    }
}

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.http.HttpMethod;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;

import java.io.IOException;

@Component
public class AuthInterceptor implements HandlerInterceptor {

    private final TokenService tokenService;

    public AuthInterceptor(TokenService tokenService) {
        this.tokenService = tokenService;
    }

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
            throws IOException {
        // 1. 预检请求直接放行，否则浏览器预检会被 401 拦住
        if (HttpMethod.OPTIONS.matches(request.getMethod())) {
            return true;
        }
        // 2. 非 Controller 方法（如静态资源）放行
        if (!(handler instanceof HandlerMethod)) {
            return true;
        }

        String header = request.getHeader("Authorization");
        if (header == null || !header.startsWith("Bearer ")) {
            return reject(response, "缺少访问令牌");
        }
        Long userId = tokenService.verify(header.substring(7));
        if (userId == null) {
            return reject(response, "令牌无效或已过期");
        }

        UserContext.set(userId);   // 供 Controller 读取当前用户
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
                                Object handler, Exception ex) {
        UserContext.clear();       // 与 MDC 同理，ThreadLocal 必须清理
    }

    private boolean reject(HttpServletResponse response, String message) throws IOException {
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
        response.setContentType("application/json;charset=UTF-8");
        response.getWriter().write("{\"code\":401,\"message\":\"" + message + "\"}");
        return false;
    }
}

public final class UserContext {

    private static final ThreadLocal<Long> CURRENT = new ThreadLocal<>();

    private UserContext() {
    }

    public static void set(Long userId) { CURRENT.set(userId); }

    public static Long get() { return CURRENT.get(); }

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

15:43:10.002 [8f2a1c9d4e7b3a05] INFO  c.e.l.interceptor.AuthInterceptor - preHandle /api/books
15:43:10.003 [8f2a1c9d4e7b3a05] INFO  c.e.library.web.BookController - 查询图书列表 userId=42
15:43:10.007 [8f2a1c9d4e7b3a05] INFO  c.e.library.filter.RequestIdFilter - GET /api/books -> 200 (6 ms)