java日志traceid追踪核心是主动复制+及时清理mdc：入口统一生成并绑定，线程池/异步/定时任务需手动透传与清空，日志配置须匹配%x{traceid}且字段名用常量。
Java 中日志在多线程或高并发环境下靠 MDC 追踪 TraceId，核心不是“自动继承”，而是“主动复制 + 及时清理”。MDC 本质是 ThreadLocal，线程间天然隔离；线程池复用、异步任务、定时调度都会导致上下文丢失——必须在任务执行前手动还原，执行后及时清空。
请求入口统一生成并绑定 TraceId
TraceId 必须在最外层可信入口生成，比如 Filter 或 WebMvcConfigurer 拦截器。不能在 Service 层或任意位置随意生成，否则同一请求多次调用可能产生多个 ID。
- 优先从 HTTP 请求头（如 X-Trace-Id）读取，有则复用；无则生成 UUID 或雪花 ID
- 调用 MDC.put("traceId", traceId) 绑定到当前线程
- 务必在 finally 块中 MDC.clear()，防止线程池复用时残留旧值污染后续请求
线程池任务必须包装传递 MDC
ThreadPoolExecutor 提交 Runnable/Callable 时，新线程不会自动拿到父线程的 MDC。直接 submit 原始任务，日志里 traceId 就为空。
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
- 提交前调用 MDC.getCopyOfContextMap() 获取快照
- 将该 Map 封装进任务：可在 run() 开头调用 MDC.setContextMap(map)
- 执行完毕必须 MDC.clear()，尤其在线程池场景下，不清理会导致下一个任务打印上一个请求的 traceId
- 推荐使用 Spring 的 ThreadPoolTaskExecutor.setTaskDecorator()，全局统一注入，避免每个 submit 都手写包装逻辑
异步与定时任务需单独适配
CompletableFuture、@Async、@Scheduled、XXL-JOB 等框架底层都新建线程或调度线程，MDC 不会穿透，极易漏埋点。
- CompletableFuture：禁用默认 ForkJoinPool，改用已装饰的线程池，例如 supplyAsync(fn, customExecutor)
- @Async：确保配置的 AsyncConfigurer 返回的是带 MDC 透传能力的 ThreadPoolTaskExecutor
- @Scheduled：每次执行都是干净线程，需在方法开头重新生成或从外部存储（如 Redis）读取 traceId 并 put 进 MDC
日志模板和字段名要规范落地
写了 MDC.put("traceId")，但 logback.xml 或 log4j2.xml 没配 %X{traceId}，日志里照样看不到——这是常见疏漏。
- logback.xml 中 pattern 示例：[%d{HH:mm:ss.SSS}] [%X{traceId:-}] [%t] %m%n，其中 :- 表示为空时显示空字符串
- traceId 字段名不要硬编码，定义常量类（如 public static final String TRACE_ID = "traceId"），所有地方统一引用
- 若后续扩展 spanId、rpcType 等字段，只需新增常量 + MDC.put，无需改日志模板和业务代码
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
