ThreadLocal 配合拦截器可安全传递用户上下文，需在 preHandle 中设置、afterCompletion 中 remove 清理，业务代码通过 UserContextHolder.get() 获取，注意异步线程不继承、避免内存泄漏和上下文串扰。
在 Java Web 应用中，用 ThreadLocal 配合拦截器（如 Spring 的 HandlerInterceptor）传递用户上下文（如登录用户 ID、租户信息、请求追踪 ID 等），是一种轻量、线程隔离的常见方案。关键在于：拦截器在请求进入时存入上下文，业务逻辑中随时获取，请求结束时务必清理，避免内存泄漏和上下文串扰。
定义 ThreadLocal 上下文容器
封装一个静态的 ThreadLocal，用于存储当前请求的用户上下文对象（比如 UserContext）。推荐使用 private static final 修饰，并提供 get/set/remove 方法：
示例：
public class UserContextHolder {
private static final ThreadLocal<UserContext> contextHolder = ThreadLocal.withInitial(() -> null);
public static void set(UserContext context) {
contextHolder.set(context);
}
public static UserContext get() {
return contextHolder.get();
}
public static void remove() {
contextHolder.remove(); // 必须调用！
}
}
在拦截器中完成上下文的存与清
实现 HandlerInterceptor，在 preHandle 中解析并设置上下文（如从 token、header 或 session 提取用户信息），在 afterCompletion 中主动清理 ThreadLocal：
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
立即学习“Java免费学习笔记（深入）”；
-
preHandle：解析请求头（如
X-User-ID）、JWT 或 Session，构建UserContext并调用UserContextHolder.set(...) -
afterCompletion：无论请求成功或异常，都执行
UserContextHolder.remove()—— 这一步不可省略，否则 Tomcat 线程复用会导致上下文残留 - 若使用
OncePerRequestFilter（更底层），也可在doFilterInternal的finally块中清理
业务代码中安全获取上下文
在 Service、Mapper 或工具类中，直接调用 UserContextHolder.get() 获取当前线程绑定的上下文。注意以下细节：
- 返回值可能为
null（如未登录、非 Web 调用），建议判空或配合 Optional 使用 - 不要在异步线程（如
@Async、线程池 submit）中直接访问 —— 子线程不继承父线程的ThreadLocal，需手动透传 - 若需跨线程传递，可用
InheritableThreadLocal（仅限父子线程），或显式将上下文快照传入新线程
规避常见陷阱
ThreadLocal 用不好容易引发问题，重点关注：
- 忘记 remove()：导致线程复用时数据污染，尤其在 Tomcat/Jetty 的线程池场景下极易出错
-
在 finally 块中 remove()：确保即使发生异常也能清理（拦截器的
afterCompletion已天然满足） -
上下文对象可变性：
UserContext建议设计为不可变（final 字段 + 构造器初始化），避免被意外修改 -
Spring AOP 代理失效：若通过
this.method()调用内部方法，AOP 不生效，但 ThreadLocal 不受影响，它只依赖线程绑定
