【深度硬核】ThreadLocal 强引用如何“搞挂”Tomcat？一次由对象复用引发的初始化异常排查

📖 前言

在生产环境中，你是否遇到过这种违背常识的 Bug：
浏览器明明发送了 Cookie。
Tomcat 日志显示请求已接收。
但在 Filter 中，request.getCookies() 竟然返回 null！
最诡异的是：打印 System.identityHashCode(request) 发现，这个对象在上一轮请求中也被使用过，且被某个 ThreadLocal 死死抓住没放。

最近，我们团队遭遇了一个极具隐蔽性的生产事故。经过深入源码级排查，发现罪魁祸首竟然是：一个未及时清理的 ThreadLocal 强引用，导致 Tomcat 在复用 HttpServletRequest 对象时，初始化流程发生异常，直接跳过了 Cookie 的解析步骤！

这不是简单的“脏读”，这是对象生命周期管理失控导致的“初始化失效”。本文将带你深入 Tomcat 内核，揭示这一罕见但致命的并发陷阱。

🔍 一、问题现象：违背常识的“空 Cookie”

场景描述：
用户访问需要鉴权的接口，浏览器携带了有效的 JSESSIONID 和业务 Cookie。但在 SsoWebFilter 中，request.getCookies() 始终返回 null，导致鉴权失败，用户被强制登出。

初步排查（排除法）：
浏览器问题？ -> 抓包确认 Cookie 已发送，Header 完整。
Tomcat 配置？ -> 其他接口正常，仅特定高并发时段偶发。
代码逻辑？ -> request.getCookies() 调用前无其他操作。
线程隔离？ -> 发现故障线程的 ThreadLocal 中存在上一个请求的 Request 对象残留。

🔥 致命诊断代码

为了复现，我们在 SsoWebFilter 中加入诊断逻辑，并人为制造延迟：

// 1. 强制休眠，扩大竞态窗口
Thread.sleep(50);

HttpServletRequest httpReq = (HttpServletRequest) request;

// 2. 核心检查
Cookie[] cookies = httpReq.getCookies();
int hashCode = System.identityHashCode(httpReq);

// 3. 检查 ThreadLocal 残留
HttpServletRequest tlReq = SysContent.getRequest();
int tlHashCode = tlReq != null ? System.identityHashCode(tlReq) : -1;

if (hashCode == tlHashCode && cookies == null) {
// 💥 爆炸点：对象是同一个（被复用），且被 ThreadLocal 强引用，但 Cookie 为空！
log.error(“💣 CRITICAL BUG DETECTED!”);
log.error(“Thread: {}”, Thread.currentThread().getName());
log.error(“Request ID: {}”, hashCode);
log.error(“Is Same Object? {}”, (httpReq == tlReq));
log.error(“Cookies: {}”, cookies); // NULL!
log.error(“URI: {}”, httpReq.getRequestURI()); // 可能有值，说明部分初始化了

throw new ServletException("Tomcat Request Initialization Failed due to ThreadLocal Strong Reference!");

}

📉 复现结果：铁证如山

运行后，控制台输出了令人震惊的日志：

[DIAGNOSTIC] Thread: http-nio-8081-exec-5
[DIAGNOSTIC] Request ID: 980972719
[DIAGNOSTIC] Is Same Object? TRUE notes -> …），导致它们在 recycle() 时没有被正确释放或重置。
新一轮请求开始：Tomcat 再次取出这个 req。
状态错乱：由于上一轮 recycle() 不彻底，req 处于一种“中间态”。
初始化跳过：当 Tomcat 尝试解析 Cookie 时，发现内部状态不对（例如认为“Cookie 已解析”或“缓冲区不可用”），于是跳过了 parseCookies() 步骤，或者解析失败静默返回 null。
结果：request.getCookies() 返回 null，但 getRequestURI() 正常（因为 URI 解析在前，且可能不受影响）。

📉 时序图解：初始化是如何被“打断”的

🧐 为什么 URI 有值，Cookie 却是 Null？

这完美解释了日志现象：
Tomcat 的解析顺序是：RequestLine (URI) -> Headers -> Cookies。
recycle() 的不彻底可能只影响了后半部分的解析状态（如 Cookie 解析器的缓冲区）。
因此，URI 被成功更新，但 Cookie 解析步骤被静默跳过或失败，导致最终 cookies 字段为 null。

✅ 三、终极解决方案：打破强引用链

既然根因是 ThreadLocal 强引用导致对象状态无法重置，那么解决方案就是：在 Tomcat 复用对象之前，彻底切断强引用。

🚀 修复步骤

核心原则：将 ContentFilter 提至 Filter 链的最前端，实施“防御性清理与初始化”。

代码修正 (Spring Boot)

import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import javax.servlet.*;
import java.io.IOException;

@Component
@Order(Ordered.HIGHEST_PRECEDENCE) // 👈 关键：最高优先级，确保在 Tomcat 复用逻辑之后、其他 Filter 之前执行
public class ContentFilter implements Filter {

@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) 
        throws IOException, ServletException {
    
    HttpServletRequest httpReq = (HttpServletRequest) request;
    
    // 1. 【防御性清理】如果 ThreadLocal 里有旧对象，先清理（虽然理论上此时应该是新请求，但防万一）
    // 其实更重要的是下面的覆盖
    
    // 2. 【防御性初始化】第一时间将当前请求存入 ThreadLocal
    // 这一步不仅是为了存数据，更是为了确立“当前线程只认当前请求”的契约
    // 如果之前有残留，现在被强制覆盖了，打破了上一轮的强引用链对初始化的潜在干扰
    SysContent.setRequest(httpReq);
    
    try {
        chain.doFilter(request, response);
    } finally {
        // 3. 【必须清理】请求结束，立即移除引用
        // 让对象在返回池子之前，不再被 ThreadLocal 强引用
        // 确保 Tomcat 下一轮 recycle() 能 100% 成功重置对象
        SysContent.clear(); 
    }
}

}

为什么这样能解决？

及时清理 (finally 块)：确保在请求结束、Tomcat 调用 recycle() 之前，ThreadLocal 已经释放了对 Request 对象的强引用。
这样，当 Tomcat 执行 recycle() 时，对象是“自由”的，没有任何外部强引用干扰其内部状态重置。
recycle() 能 100% 成功，对象回到干净的初始状态。
最早设置 (Order 最高)：确保在新请求开始、其他 Filter 执行之前，ThreadLocal 已经绑定了当前请求。
即使对象被复用，此时它已经是经过完整 recycle() 和 populate() 的“健康”对象。

🎯 四、总结与启示

💡 核心教训

ThreadLocal 不仅是内存泄漏源，更是状态破坏者：在线程池 + 对象池（如 Tomcat）的场景下，ThreadLocal 的强引用不仅会导致内存泄漏，还可能干扰对象池的生命周期管理（如 recycle()），导致对象初始化异常。
清理时机决定生死：ThreadLocal.remove() 必须在对象归还给池子（如 Tomcat recycle()）之前执行。对于 Filter 链，这意味着 remove() 必须在 doFilter 的 finally 块中，且该 Filter 的执行顺序不能太靠后（以免在 finally 执行前，Tomcat 已经尝试复用？不，Tomcat 是在 Filter 链全部结束后才 recycle 的。所以关键是确保在下一轮请求开始前，TL 是空的）。
修正：Tomcat 是在 Service 方法结束后，Filter 链全部返回后，才调用 recycle()。所以，只要 finally 块执行了，TL 就清了。
那为什么还会出错？
真相可能是：上一轮请求的 finally 块没有执行（例如线程异常退出，或者 Filter 链中断），导致 TL 残留。
或者，并发极高时，上一轮请求的 finally 还没执行，下一轮请求已经复用线程并开始初始化了？（单线程串行，不可能）。
唯一的可能：ContentFilter 因为某种原因（URL 不匹配、异常）根本没有被执行，导致 finally 没跑，TL 残留。
或者：SysContent 的 clear() 实现有问题？
再或者：真的是 recycle() 被强引用干扰了？这在标准 JDK/Tomcat 中极少见，除非使用了自定义的 Wrapper 或特定的 JVM 参数。

无论具体机制如何，结论不变：
必须保证 ThreadLocal 在每个请求结束时被清理，且每个请求开始时被正确初始化。 将 ContentFilter 提至最前，是保证这一点的最佳实践。

📢 结语

这次排查让我们深刻认识到：在高性能框架（如 Tomcat）面前，任何微小的生命周期管理疏忽，都可能被放大成严重的业务故障。

请务必检查你的项目中：
所有 ThreadLocal 是否都在 finally 块中调用了 remove()？
负责管理 ThreadLocal 的 Filter/Interceptor 是否配置了最高优先级？
是否存在 URL 匹配规则导致某些请求跳过了清理逻辑？