Java Interceptor有哪些最佳实践

Java Interceptor 最佳实践

一 概念与适用边界

• 明确拦截器类型：在 Java Web 场景中，通常指 Spring MVC 的 HandlerInterceptor，围绕 preHandle / postHandle / afterCompletion 三个阶段执行，适合做登录鉴权、接口耗时统计、业务参数预处理等。与之相邻但不同的 Servlet Filter 工作在更底层，面向所有请求（含静态资源），更适合编码转换、XSS/限流等通用 Web 层处理。二者可组合使用但要控制顺序与职责边界。拦截器依赖 Spring 上下文，能直接访问 Bean；过滤器不依赖 Spring，通用性更强。

二 设计与实现

• 单一职责：每个拦截器只做一件事（如鉴权、日志、监控），通过组合多个拦截器形成“责任链”，便于维护与复用。保持逻辑轻量，避免在拦截器中做耗时操作（如远程调用、复杂计算）。
• 线程安全：拦截器通常是单例，不要定义可变的实例字段；如需传递数据，使用 ThreadLocal 并在完成后及时清理，避免内存泄漏与跨请求污染。
• 路径与顺序：通过 addPathPatterns / excludePathPatterns 精确控制拦截范围，白名单如登录、静态资源、健康检查、Swagger 文档等应排除；注册顺序即执行顺序，结合 @Order 或显式注册顺序管理链路。
• 异常处理：在 preHandle 中如需中断请求，直接返回 false 并写入响应；Controller 层异常建议交由 @ControllerAdvice 统一处理；afterCompletion 可用于兜底记录与资源清理（能感知异常）。
• 性能与 I/O：避免在拦截器中进行阻塞 I/O；对高频读操作（如鉴权规则、黑白名单）使用缓存（如 Redis）；必要时采用异步或消息解耦，降低请求时延与峰值压力。

三 配置与注册

• 标准注册：实现 WebMvcConfigurer 的 addInterceptors 方法完成注册，按需设置路径匹配与顺序；拦截器 Bean 可 @Component 注入，便于与 Spring 生态集成。
• 动态配置：将 excludes 等规则外置到配置（如 @ConfigurationProperties），支持热更新与多环境差异化；在网关/业务层合理分工鉴权，避免重复校验与冲突。
• 组合使用 Filter 与 Interceptor：遵循 FilterChain 顺序 > Interceptor 顺序；Filter 处理通用 HTTP 层横切（编码、压缩、安全基线），Interceptor 处理业务语义更强的横切（权限、日志追踪）。必要时在 Filter 中设置响应头、在 Interceptor 中访问业务 Bean。

四 可观测性与测试

• 请求链路追踪：在 preHandle 记录开始时间或 traceId，在 afterCompletion 计算耗时并输出结构化日志，必要时上报到链路追踪系统，便于定位性能瓶颈与故障根因。
• 集成测试：使用 MockMvc 对拦截器链路进行端到端验证，覆盖白名单、鉴权失败、异常路径与顺序依赖；为关键拦截器补充单元测试与性能基准测试，确保在高并发下仍满足 RT/吞吐 目标。

五 常见陷阱与规避

• 忽略执行时机：在 preHandle 中忘记返回 true 会导致后续拦截器与 Controller 不执行；在 postHandle 修改 ModelAndView 时要注意视图是否已渲染或为空。
• 静态资源误拦截：对 / 拦截时要显式 excludePathPatterns 常见静态资源与文档路径，避免 404/性能浪费。
• 过度耦合与重复处理：将网关层与业务层鉴权职责厘清，避免同一请求被多次校验；对跨层级数据传递优先使用请求属性或 ThreadLocal，并在 afterCompletion 清理。
• 忽视异常处理路径：afterCompletion 能感知异常，适合做统一补偿与审计；不要在 preHandle 吞掉异常导致链路“静默失败”。
• 配置不可变：将白名单与规则写死在代码中难以维护，建议使用配置中心或 @ConfigurationProperties 动态下发，配合监听与热更新机制。