threadlocal 与 mdc 配合实现日志 traceid 追踪，核心是利用 threadlocal 线程隔离性在请求入口生成唯一 traceid 并通过 mdc 绑定到日志上下文，使同线程日志自动携带；普通变量无法自动注入每条日志，手动拼接侵入业务且易遗漏。
ThreadLocal 与 MDC 配合实现日志 traceId 追踪，核心在于利用 ThreadLocal 的线程隔离特性，在请求入口生成唯一 traceId，并通过 MDC 将其绑定到当前线程的日志上下文中，使同一线程内所有日志自动携带该 traceId。
为什么用 ThreadLocal + MDC 而不是直接用普通变量？
MDC（Mapped Diagnostic Context）是 Logback/Log4j 提供的线程级日志上下文容器，底层正是基于 ThreadLocal 实现。它允许你在日志输出模板中（如 %X{traceId}）动态插入键值对。直接用普通变量无法做到“每条日志自动带上”，而手动在每个 logger.info() 里拼接 traceId 又侵入业务、易遗漏。ThreadLocal 保证了不同请求线程互不干扰，MDC 则把这种隔离能力无缝对接到日志框架。
你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。 它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在
典型使用流程（Spring Web 环境）
- 请求进入时生成并注入 traceId：在 Filter 或 Spring 拦截器中生成唯一 ID（如 UUID 或 Snowflake），调用 MDC.put("traceId", id)
- 日志配置中启用 traceId 输出：logback.xml 中 pattern 设置为 %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %X{traceId} - %msg%n
- 请求结束时清理 MDC：在 Filter 的 finally 块或拦截器 afterCompletion 中调用 MDC.clear()，防止线程复用导致 traceId 泄露（尤其在 Tomcat 线程池场景下）
注意线程切换导致的 traceId 丢失问题
默认情况下，MDC 是 ThreadLocal 的，子线程不会自动继承父线程的 MDC 内容。遇到异步操作（如 CompletableFuture、@Async、线程池提交任务）时需手动传递：
- 使用 MDC.getCopyOfContextMap() 获取当前上下文快照
- 在线程创建/提交前，用 MDC.setContextMap(...) 注入到新线程
- 推荐封装工具类或使用支持 MDC 透传的线程池（如 Logbook、TTL 或自定义 ThreadPoolTaskExecutor）
不建议自己重复造轮子
Spring Cloud Sleuth、SkyWalking Agent、OpenTelemetry SDK 等已内置完善的 traceId 生成、传播与 MDC 集成逻辑，支持跨进程（HTTP/GRPC）、跨线程、跨消息队列。除非轻量级项目或学习目的，否则优先接入标准分布式追踪方案，避免 traceId 不一致、漏埋点、透传失败等问题。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
