ThreadLocal规范使用需明确生命周期、防内存泄漏、封装访问逻辑、禁用裸实例；必须用withInitial()、强制清理、限制存轻量不可变上下文，禁止跨线程传递或存大对象。
ThreadLocal 工具类要写得规范、安全、可维护，核心是：**明确生命周期、避免内存泄漏、封装访问逻辑、禁止裸用 ThreadLocal 实例**。团队滥用往往源于直接 new ThreadLocal()、忘记 remove()、跨线程传递或在池化线程（如 Tomcat 线程池、CompletableFuture）中长期持有值。
统一提供静态工具方法，禁用 public ThreadLocal 字段
不暴露原始 ThreadLocal 实例，所有读写通过静态方法控制，便于统一审计、增强和未来替换（如改用 MDC 或上下文透传）。
- ✅ 正确示例：
public final class RequestContext {
private static final ThreadLocal<String> TRACE_ID = ThreadLocal.withInitial(() -> UUID.randomUUID().toString());
private RequestContext() {}
public static String getTraceId() {
return TRACE_ID.get();
}
public static void setTraceId(String traceId) {
TRACE_ID.set(traceId);
}
public static void clear() {
TRACE_ID.remove();
}
}
- ❌ 禁止写法：
public static final ThreadLocal<string> TRACE_ID = new ThreadLocal();</string>（无初始值、不可控、易被误用） - ✅ 建议 always 使用
withInitial()，避免 get() 返回 null 引发 NPE
强制绑定清理时机，尤其在 Web 和异步场景
ThreadLocal 值不会自动释放，线程复用（如 Servlet 容器、线程池）下极易堆积旧值，造成内存泄漏或上下文污染。
- Web 场景：在 Filter 最外层 doFilter() 结尾调用
RequestContext.clear() - 异步场景（如 CompletableFuture）：若需跨线程传递上下文，不要依赖 ThreadLocal —— 改用显式参数传递、InheritableThreadLocal（慎用，有局限）、或封装上下文对象手动传播
- 定时任务/线程池任务：在 Runnable/Callable 执行前后 wrap 清理逻辑，例如用装饰器模式：
public static <T> Callable<T> withCleanContext(Callable<T> task) {
return () -> {
try {
return task.call();
} finally {
RequestContext.clear();
}
};
}
限制存储内容：只存轻量、不可变、业务强相关上下文
ThreadLocal 不是通用缓存，更不是跨方法传参的捷径。
立即学习“Java免费学习笔记（深入）”；
- ✅ 推荐存：traceId、userId（认证后）、tenantId、请求开始时间、日志 MDC 键值
- ❌ 禁止存：大对象（如 DTO、List）、数据库连接、流、锁、Spring Bean（会破坏作用域语义）
- ⚠️ 警惕“懒人传参”：用 ThreadLocal 替代方法参数传递，会让调用链隐式依赖，难以测试和追踪
配套文档 + 静态检查（可选但强烈建议）
光靠约定难落地，需工程化约束：
- 在公司内部代码规约中明确 ThreadLocal 使用红线（如“所有 ThreadLocal 必须封装在 XxxContext 类中，且必须提供 clear()”）
- 用 SonarQube 或自定义 PMD 规则拦截
new ThreadLocal()、未调用remove()的典型模式 - 在 CI 中加入字节码扫描，检测 ThreadLocal 子类是否重写了 finalize（已过时，但说明有人试图兜底 —— 应杜绝）
不复杂但容易忽略：ThreadLocal 是把双刃剑，规范不在限制使用，而在让每次使用都清晰、可控、可追溯。
