ThreadContext 是 Log4j2（非 Java 原生）提供的线程上下文工具，需引入 log4j-api 和 log4j-core（≥2.7），配合 %X{key} 在 PatternLayout 中显式输出，且须手动清理、注意异步线程不自动继承。
ThreadContext 是 Log4j2 的东西，不是 Java 原生 API
Java 标准库没有 ThreadContext；它属于 Log4j2（2.x 版本），用来在日志中自动携带线程级上下文数据。很多人搜“Java 异常上下文注入”，结果误以为这是 JDK 自带能力，实际一写 ThreadContext.put() 就报 NoClassDefFoundError 或 IDE 找不到类——缺的是 Log4j2 依赖，不是代码写错了。
常见错误现象：java.lang.NoClassDefFoundError: org/apache/logging/log4j/ThreadContext
- 确认项目已引入 Log4j2：Maven 里要有
log4j-api和log4j-core，且版本 ≥ 2.7（ThreadContext的put()在 2.7+ 才支持结构化存储） - 别混用 Log4j1（
org.apache.log4j.MDC）和 Log4j2——两者不兼容，MDC.put()和ThreadContext.put()行为也不同 - Spring Boot 2.4+ 默认弃用 Log4j2，改用 Logback；若强行换回 Log4j2，需排除
spring-boot-starter-logging并显式引入 Log4j2 starter
异常捕获时往 ThreadContext 写用户信息，必须手动清理
Log4j2 的 ThreadContext 基于 InheritableThreadLocal 实现，不自动清空。一次请求里写入的 userId、traceId 等，如果没主动删，可能泄漏到后续请求（尤其线程复用场景，如 Tomcat 线程池）。
使用场景：Web 过滤器或 Spring AOP 拦截 Controller 方法，在 try-catch 的 catch 块里记录异常前注入上下文
立即学习“Java免费学习笔记（深入）”；
你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。 它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在
- 写法示例：
ThreadContext.put("userId", String.valueOf(user.getId())); - 必须配对清理：
ThreadContext.clear();或更精准地ThreadContext.remove("userId"); - 别依赖 finally 块——如果异常发生在
ThreadContext.put()之后、finally之前，清理逻辑就跳过了；推荐用 try-with-resources 封装上下文生命周期，或统一在过滤器末尾清理
Log4j2 配置里不启用 %X 或 %mdc，日志里根本看不到上下文
ThreadContext.put() 只是存数据，要让它出现在日志行里，得靠 PatternLayout 的转换器。默认配置（比如 Spring Boot 的 console pattern）通常不含上下文字段，所以即使存了，日志里也只显示空括号或干脆没影。
性能影响：%X 是轻量级字符串拼接，但若存的是大对象（比如把整个 User 实例 toString() 后塞进去），会拖慢日志输出速度
- Pattern 示例：
%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %X{userId} %X{traceId} - %msg%n - 注意
%X{key}和%X区别：%X输出全部键值对（JSON 格式），%X{userId}只取单个字段 - 如果 key 不存在，
%X{userId}默认输出空字符串；加个默认值可写成%X{userId:-unknown}
异步日志下 ThreadContext 不会自动传递给子线程
Log4j2 默认异步日志（AsyncLogger）用独立线程刷盘，而 ThreadContext 是线程绑定的。主线程里 put("userId", "1001")，异步线程里读出来是空——这导致错误日志里 userId 字段全丢。
解决方法不是关异步（性能代价大），而是启用上下文继承：
- Log4j2.xml 中配置
AsyncLoggerConfig时加属性：includeLocation="true"不管用，关键得设isIncludeLocation="false"并确保ThreadContextMap实现支持继承（Log4j2 2.17+ 默认DefaultThreadContextMap已开启useMapInheritance=true） - 更稳的方式：用
ThreadContext.put("userId", ...)后，立刻在日志语句里显式传参，比如logger.error("DB timeout", userId, e);，再配合自定义 Layout 提取参数 - Spring 环境可用
@Scope("prototype")的 MDC 工具类包装，但本质还是绕开异步线程隔离问题
真正容易被忽略的点：ThreadContext 的“上下文”只对当前线程有效，任何跨线程操作（CompletableFuture、@Async、new Thread）都得自己做 copy，Log4j2 不帮你兜底。
