拦截器常见错误有哪些

拦截器（Interceptor）在软件开发中应用广泛，常见于 Web 框架（如 Spring、Struts2）、RPC 框架（如 Dubbo）、以及前端请求库（如 Axios、OkHttp）。虽然概念相似，但不同场景下的常见错误略有不同。

以下从通用逻辑错误、Spring MVC 拦截器、前端 Axios 拦截器以及RPC/微服务拦截器四个维度，为你梳理拦截器中最高频的常见错误及避坑指南。

一、 通用逻辑错误（适用于所有场景）

1. 无限循环与死循环

这是最容易犯的错误，通常是因为拦截器内部又触发了同一个拦截器。

• 场景：在拦截器中为了重试或补充 Token，重新发起请求。
• 错误示例：

  // 伪代码：拦截器中重试请求
  if (tokenExpired) {
      // 重新获取 token
      login();
      // 重新发起请求 -> 又会进入这个拦截器 -> 死循环
      return client.execute(request); 
  }
  

• 解决方案：设置一个最大重试次数（Retry Count）或在请求头中加标记位，避免重复拦截。

2. 异常处理不当（吞掉异常）

拦截器是“守门员”，如果异常处理不好，会导致上游业务完全不知道发生了什么。

• 错误：在 catch 块中仅仅打印日志，不抛出异常，也不返回错误响应。
• 后果：调用方一直等待，或者收到一个空的、不合法的成功响应。
• 解决方案：要么抛异常，要么返回一个明确的错误对象/响应码。

3. 修改不可变的请求/响应对象

• 错误：试图直接修改只读的请求对象（如 HttpServletRequest 的输入流只能读一次）。
• 后果：getInputStream() 第二次读取时报 IllegalStateException。
• 解决方案：使用装饰器模式（Wrapper）包装请求对象，缓存 Body 内容。

4. 忽略执行链（忘记调用 proceed / invoke / next）

拦截器通常是一个链（Chain），如果你不调用下一个节点，请求就断了。

• 错误：重写方法后，没有调用 chain.proceed() 或 invocation.invoke()。
• 后果：请求根本没有到达 Controller 或服务提供者。
• 解决方案：确保有调用链路的代码。

二、 Spring MVC 拦截器 (HandlerInterceptor) 常见错误

1. 拦截范围配置错误

• 错误：配置 addPathPatterns 时，路径写错或漏写，导致拦截器不生效。
• 示例：

  @Override
  public void addInterceptors(InterceptorRegistry registry) {
      // 错误：只拦截 /api/* (一级目录)，不会拦截 /api/user/list
      registry.addInterceptor(new MyInterceptor()).addPathPatterns("/api/*");
      
      // 正确：拦截 /api 下的所有路径
      registry.addInterceptor(new MyInterceptor()).addPathPatterns("/api/**");
  }
  

• 注意：/* 只匹配一级路径，/** 匹配多级路径。

2. 拦截器注册顺序问题

• 错误：期望拦截器 A 先执行，B 后执行，但结果相反。
• 原因：Spring 中拦截器的执行顺序取决于注册顺序。在 Spring Boot 中，可以通过 @Order 或实现 Ordered 接口，或者调整 addInterceptors 的调用顺序来控制。

3. 在 preHandle 中读取 Request Body 导致 Controller 无法读取

• 原因：@RequestBody 默认只能读取一次 InputStream。如果在拦截器中通过 request.getInputStream() 读取了 Body（例如为了做签名验证），Controller 里的参数就会是空的。
• 解决方案：使用 ContentCachingRequestWrapper 或自定义 HttpServletRequestWrapper 包装器，缓存 Body 数据。

4. 静态资源被拦截

• 错误：没有排除静态资源（如 .css, .js, /swagger-ui/**），导致页面样式丢失或 Swagger 无法访问。
• 解决方案：在配置中明确排除：

  registry.addInterceptor(new MyInterceptor())
          .addPathPatterns("/**")
          .excludePathPatterns("/css/**", "/js/**", "/swagger-ui/**");
  

三、 前端拦截器 (Axios/Fetch) 常见错误

1. Token 刷新时的并发冲突（经典面试题）

• 场景：页面同时发起 5 个请求，Token 都过期了。
• 错误：5 个请求的拦截器同时去刷新 Token，导致发了 5 次刷新请求，或者前一个刷新的 Token 被后一个覆盖。
• 解决方案：使用 “请求挂起队列” 机制。第一个请求去刷新 Token，剩下的请求排队等待，Token 刷新完后，再用新 Token 重试队列里的请求。

2. 在响应拦截器中忘记返回 Response

• 错误：

  axios.interceptors.response.use(response => {
      // 这里只处理了数据，没 return
      return response.data; // 如果这里什么都不 return，后续的 then 拿不到数据
  });
  

• 后果：后续的 .then() 拿到的数据是 undefined。

3. 循环调用导致堆栈溢出

• 场景：在响应拦截器中，如果 Token 过期，自动刷新并重新发起原请求。
• 错误：重新发起请求时，没有判断是否正在刷新，或者没有终止当前逻辑，导致无限的 401 -> 刷新 -> 请求 -> 401。

四、 RPC/微服务拦截器 (Dubbo/gRPC) 常见错误

1. 重度阻塞操作

• 错误：在 RPC 拦截器中做重量级操作，如复杂计算、同步数据库查询、Thread.sleep。
• 后果：RPC 调用通常是高并发的，拦截器在主链路中，会严重拖慢整体吞吐量。
• 建议：只做轻量级的校验（鉴权、日志、上下文传递）。

2. 上下文丢失（Context Loss）

• 错误：在 Dubbo 或微服务中，通过拦截器设置了 RpcContext 或 ThreadLocal 的变量，但在异步线程池（Async）中执行时，发现变量没了。
• 原因：ThreadLocal 是线程绑定的，异步切换线程后就没了。
• 解决方案：使用 TransmittableThreadLocal (TTL) 或者在提交任务时手动传递上下文。

3. 拦截器顺序与覆盖问题

• 错误：定义了多个拦截器，但是后注册的拦截器覆盖了前一个拦截器的 Attachment（附加参数）。
• 建议：在设置 Attachment 时，检查 Key 是否已存在，或者使用唯一的 Key 命名空间。

五、 总结 checklist

如果你在调试拦截器，请检查以下几点：

1. 路径对不对？ (/** vs /*)
2. 链条调没调用？ (chain.proceed() / invocation.invoke())
3. Body 能重复读吗？ (Request 流只能读一次)
4. 异常抛出去了吗？ (不要吞掉异常)
5. 死循环了吗？ (重试逻辑是否加了次数限制)
6. 顺序对吗？ (注册顺序是否符合预期)

通过避免这些常见错误，可以大大减少在拦截器上花费的调试时间。