在 Spring Boot 开发体系中，拦截器（Interceptor）是堪称 "瑞士军刀" 般的存在。这个诞生于 Spring MVC 框架的核心组件，通过对请求处理全链路的无缝切入，为开发者提供了预处理、后处理的强大能力。本文将深度解析 6 大典型应用场景，带你从入门到精通拦截器的实战技巧。

一、权限校验：构建系统安全第一道防线

在前后端分离架构中，接口权限控制是刚需。拦截器可在请求到达控制器前，完成用户身份验证和权限校验，避免非法请求浪费系统资源。

实现要点：

1. 从 HttpServletRequest 获取 token（通常在请求头中）
2. 调用认证中心接口验证 token 有效性
3. 根据用户角色匹配接口访问权限

java

public class AuthInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, 
                             HttpServletResponse response, 
                             Object handler) {
        String token = request.getHeader("Authorization");
        if (StringUtils.isEmpty(token)) {
            sendErrorResponse(response, 401, "未提供认证令牌");
            return false;
        }
        AuthResult authResult = authClient.validateToken(token);
        if (!authResult.isValid()) {
            sendErrorResponse(response, 403, "无效的认证令牌");
            return false;
        }
        // 将用户信息存入ThreadLocal
        UserContextHolder.setCurrentUser(authResult.getUser());
        return true;
    }

    private void sendErrorResponse(HttpServletResponse response, 
                                   int status, String message) throws IOException {
        response.setStatus(status);
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        try (PrintWriter writer = response.getWriter()) {
            writer.write(JSON.toJSONString(Result.error(status, message)));
        }
    }
}

最佳实践：

• 采用黑白名单机制，对公共接口（如登录、注册）设置排除路径
• 使用 ThreadLocal 存储当前用户信息，方便后续业务逻辑获取
• 结合 Spring EL 表达式实现细粒度权限控制（如 @PreAuthorize）

二、日志追踪：打造全链路请求监控体系

在微服务架构中，请求链路追踪至关重要。拦截器可记录请求的关键信息，为系统调优和故障排查提供依据。

核心功能：

1. 记录请求时间、URI、HTTP 方法
2. 采集客户端 IP、User-Agent 等环境信息
3. 统计接口响应时间
4. 记录异常请求堆栈信息

java

public class RequestLogInterceptor implements HandlerInterceptor {
    private static final Logger LOGGER = LoggerFactory.getLogger(RequestLogInterceptor.class);

    private ThreadLocal<Long> startTime = new ThreadLocal<>();

    @Override
    public void preHandle(HttpServletRequest request, 
                          HttpServletResponse response, 
                          Object handler) {
        startTime.set(System.currentTimeMillis());
        LOGGER.info("请求开始：{} {}", request.getMethod(), request.getRequestURI());
        // 记录请求参数
        logParameters(request);
    }

    private void logParameters(HttpServletRequest request) {
        Map<String, String[]> parameterMap = request.getParameterMap();
        if (!parameterMap.isEmpty()) {
            LOGGER.info("请求参数：{}", parameterMap.entrySet().stream()
                .collect(Collectors.toMap(Map.Entry::getKey, 
                    entry -> Arrays.toString(entry.getValue()))));
        }
    }

    @Override
    public void afterCompletion(HttpServletRequest request, 
                                HttpServletResponse response, 
                                Object handler, 
                                Exception ex) {
        long endTime = System.currentTimeMillis();
        LOGGER.info("请求结束：{} 耗时{}ms 状态码{}", 
            request.getRequestURI(), 
            endTime - startTime.get(), 
            response.getStatus());
        startTime.remove();
        // 记录异常信息
        if (ex != null) {
            LOGGER.error("请求处理异常：", ex);
        }
    }
}

进阶应用：

• 结合 MDC（Mapped Diagnostic Context）实现分布式链路追踪
• 使用 AOP 对日志记录逻辑进行二次封装
• 支持日志级别动态配置（开发环境记录详细信息，生产环境简化日志）

三、参数处理：实现请求数据统一格式化

在实际开发中，经常需要对请求参数进行统一处理，比如：

• 字符串去空格、转义
• 日期格式统一转换
• 特殊符号过滤
• 数据格式校验

实现方案：

java

public class ParameterInterceptor implements HandlerInterceptor {
    private static final Pattern SPECIAL_CHAR_PATTERN = Pattern.compile("[^a-zA-Z0-9_]");

    @Override
    public boolean preHandle(HttpServletRequest request, 
                             HttpServletResponse response, 
                             Object handler) {
        // 处理路径参数
        Map<String, String> pathVariables = getPathVariables(request);
        processParameters(pathVariables);
        
        // 处理查询参数
        Map<String, String[]> queryParams = request.getParameterMap();
        processParameters(queryParams);
        
        // 处理表单参数（需要支持PUT/POST等方法）
        if (isFormRequest(request)) {
            Map<String, String[]> formParams = parseFormParameters(request);
            processParameters(formParams);
            // 重新封装请求参数
            request = new ParameterRequestWrapper(request, formParams);
        }
        return true;
    }

    private void processParameters(Map<String, ?> params) {
        params.forEach((key, value) -> {
            if (value instanceof String) {
                String processedValue = SPECIAL_CHAR_PATTERN.matcher((String) value)
                    .replaceAll("")
                    .trim();
                params.put(key, processedValue);
            } else if (value instanceof String[]) {
                String[] processedValues = Arrays.stream((String[]) value)
                    .map(v -> SPECIAL_CHAR_PATTERN.matcher(v).replaceAll("").trim())
                    .toArray(String[]::new);
                params.put(key, processedValues);
            }
        });
    }
}

注意事项：

• 对于 PUT/POST 请求，需要自定义 RequestWrapper 来修改请求参数
• 支持参数校验失败后的统一异常处理
• 结合 @Valid 注解实现更强大的参数校验功能

四、响应封装：实现统一格式的 API 输出

在 RESTful API 设计中，统一的响应格式有助于前后端协作，拦截器可在响应返回前对数据进行统一封装。

标准响应结构：

json

{
    "code": 200,
    "message": "成功",
    "data": { ... }
}

实现步骤：

1. 创建响应包装器类
2. 在 postHandle 方法中拦截响应内容
3. 将原始响应数据封装成标准格式
4. 通过 ResponseWrapper 修改输出内容

java

public class ResponseInterceptor implements HandlerInterceptor {

    @Override
    public void postHandle(HttpServletRequest request, 
                           HttpServletResponse response, 
                           Object handler, 
                           Object responseBody) {
        if (responseBody instanceof ResponseEntity) {
            ResponseEntity<?> entity = (ResponseEntity<?>) responseBody;
            Object body = entity.getBody();
            // 封装响应数据
            Result result = Result.success(body);
            // 重新设置响应体
            ((HandlerMethod) handler).getMethodAnnotation(ResponseBody.class);
            request.setAttribute("RESPONSE_RESULT_ENTITY", 
                new ResponseEntity<>(result, entity.getHeaders(), entity.getStatusCode()));
        }
    }
}

高级技巧：

• 支持不同版本 API 的响应格式兼容
• 对下载文件等特殊响应进行排除处理
• 结合 Jackson 自定义序列化规则

五、跨域处理：优雅解决前后端跨域问题

虽然 Spring Boot 提供了 @CrossOrigin 注解，但在复杂场景下，拦截器能提供更灵活的跨域解决方案。

处理流程：

1. 检测 OPTIONS 预 flight 请求
2. 设置跨域响应头（Access-Control-Allow-Origin、Access-Control-Allow-Methods 等）
3. 支持动态跨域白名单配置

java

public class CorsInterceptor implements HandlerInterceptor {

    private Set<String> allowedOrigins = new HashSet<>();

    public CorsInterceptor(Set<String> allowedOrigins) {
        this.allowedOrigins.addAll(allowedOrigins);
    }

    @Override
    public boolean preHandle(HttpServletRequest request, 
                             HttpServletResponse response, 
                             Object handler) {
        String origin = request.getHeader("Origin");
        if (allowedOrigins.contains(origin)) {
            response.setHeader("Access-Control-Allow-Origin", origin);
            response.setHeader("Access-Control-Allow-Credentials", "true");
            response.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
            response.setHeader("Access-Control-Allow-Headers", 
                "Authorization, Content-Type, X-Requested-With");
        }
        // 处理预flight请求
        if ("OPTIONS".equals(request.getMethod())) {
            response.setStatus(HttpServletResponse.SC_OK);
            return false;
        }
        return true;
    }
}

最佳实践：

• 结合 Nginx 实现生产环境的跨域处理
• 支持携带 cookie 的跨域请求
• 实现动态白名单管理（通过数据库或配置中心）

六、性能监控：精准定位系统性能瓶颈

在系统优化过程中，需要对接口性能进行监控，拦截器可方便地实现接口响应时间统计。

实现逻辑：

1. 在 preHandle 记录请求开始时间
2. 在 afterCompletion 计算响应时间
3. 将性能数据输出到日志或发送到监控系统

java

public class PerformanceInterceptor implements HandlerInterceptor {

    private static final Map<String, Long> performanceMetrics = new ConcurrentHashMap<>();

    private ThreadLocal<Long> startTime = new ThreadLocal<>();

    @Override
    public void preHandle(HttpServletRequest request, 
                          HttpServletResponse response, 
                          Object handler) {
        startTime.set(System.currentTimeMillis());
    }

    @Override
    public void afterCompletion(HttpServletRequest request, 
                                HttpServletResponse response, 
                                Object handler, 
                                Exception ex) {
        long endTime = System.currentTimeMillis();
        long duration = endTime - startTime.get();
        String uri = request.getRequestURI();
        performanceMetrics.merge(uri, duration, Long::sum);
        // 输出性能日志
        LOGGER.info("接口性能：{} 耗时{}ms", uri, duration);
        startTime.remove();
    }

    public static Map<String, Long> getPerformanceMetrics() {
        return new HashMap<>(performanceMetrics);
    }
}

扩展应用：

• 结合 Micrometer 实现与 Prometheus 的集成
• 设置性能阈值，超过阈值发送预警通知
• 支持按时间段统计接口调用次数和平均响应时间

拦截器配置最佳实践

java

@Configuration
public class InterceptorConfig implements WebMvcConfigurer {

    private final AuthInterceptor authInterceptor;
    private final RequestLogInterceptor requestLogInterceptor;
    private final ParameterInterceptor parameterInterceptor;

    public InterceptorConfig(AuthInterceptor authInterceptor, 
                             RequestLogInterceptor requestLogInterceptor, 
                             ParameterInterceptor parameterInterceptor) {
        this.authInterceptor = authInterceptor;
        this.requestLogInterceptor = requestLogInterceptor;
        this.parameterInterceptor = parameterInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(authInterceptor)
            .addPathPatterns("/api/**")
            .excludePathPatterns("/api/auth/login", "/api/auth/register");
        
        registry.addInterceptor(requestLogInterceptor)
            .addPathPatterns("/**");
        
        registry.addInterceptor(parameterInterceptor)
            .addPathPatterns("/api/**");
        
        // 其他拦截器配置...
    }
}

配置关键点：

1. 拦截顺序：先执行 preHandle，后注册的拦截器先执行
2. 路径匹配：支持 Ant 风格路径（如 /api/*、/user/**）
3. 排除路径：对静态资源、公共接口设置排除

深度思考：拦截器 vs 过滤器

很多开发者会混淆拦截器和过滤器，两者主要区别在于：

在实际开发中，应根据需求选择合适的技术方案，两者并非互斥，常配合使用以实现完整的请求处理链路。

总结

Spring Boot 拦截器凭借其灵活的生命周期回调机制，成为构建高效、健壮系统的重要工具。从基础的权限校验到复杂的性能监控，掌握这 6 大核心场景，足以应对 90% 以上的拦截器应用需求。建议开发者在实际项目中，结合具体业务场景进行扩展，打造符合项目需求的拦截器体系。记住，优秀的拦截器设计不仅能提升开发效率，更能为系统的可维护性和扩展性奠定坚实基础。

你在实际开发中遇到过哪些有趣的拦截器应用场景？欢迎在评论区分享你的经验，让我们共同探讨拦截器的更多可能性。

感谢关注【AI码力】，感谢一键三连！