如何实现跨线程传播 MDC 日志追踪 ID 的 ThreadPoolExecutor 装饰器？

本文共计907个文字，预计阅读时间需要4分钟。

Logback 或 Log4j2 的 MDC（Mapped Diagnostic Context，映射诊断上下文）本质是基于 ThreadLocal 实现的。每个线程拥有独立的 MDC Map，子线程不会自动继承父线程的 MDC 内容。当使用 ThreadPoolExecutor 提交任务时，任务通常会被调度到其他工作线程执行，而原调用线程的 MDC 无法直接传递过去，这会导致日志中缺少 traceId、userId 等关键跟踪字段。

核心思路：任务提交时捕获 + 执行前还原

要实现跨线程透传，需在任务提交时刻“快照”当前线程的 MDC 内容，并在目标线程执行任务前将其还原。这不是修改 JDK 源码，而是通过装饰器模式包装 ThreadPoolExecutor，拦截 execute() 和 submit() 方法：

• 对 Runnable / Callable 包装一层代理，在构造时拷贝父线程的 MDC
• 代理对象的 run() 或 call() 中先将 MDC 设置为快照值，执行完再清理（避免内存泄漏）
• 支持 lambda、匿名类、方法引用等所有常见任务类型

实战代码：MdcPropagatingExecutor 装饰器

以下是一个轻量、无依赖、线程安全的实现（兼容 Java 8+）：

<font size="2"><pre class="brush:php;toolbar:false;">public class MdcPropagatingExecutor implements ExecutorService { private final ExecutorService delegate; public MdcPropagatingExecutor(ExecutorService delegate) { this.delegate = delegate; } @Override public void execute(Runnable command) { delegate.execute(wrap(command)); } @Override public <T> Future<T> submit(Callable<T> task) { return delegate.submit(wrap(task)); } @Override public Future<?> submit(Runnable task) { return delegate.submit(wrap(task)); } // 其他 submit 重载和 shutdown 方法略，均委托给 delegate private Runnable wrap(Runnable task) { Map<String, String> context = MDC.getCopyOfContextMap(); return () -> { Map<String, String> prev = MDC.getCopyOfContextMap(); if (context != null) { MDC.setContextMap(context); } else { MDC.clear(); } try { task.run(); } finally { if (prev != null) { MDC.setContextMap(prev); } else { MDC.clear(); } } }; } private <T> Callable<T> wrap(Callable<T> task) { Map<String, String> context = MDC.getCopyOfContextMap(); return () -> { Map<String, String> prev = MDC.getCopyOfContextMap(); if (context != null) { MDC.setContextMap(context); } else { MDC.clear(); } try { return task.call(); } finally { if (prev != null) { MDC.setContextMap(prev); } else { MDC.clear(); } } }; } }

使用方式简单直接：

<font size="2"><pre class="brush:php;toolbar:false;">ExecutorService executor = new MdcPropagatingExecutor( Executors.newFixedThreadPool(4) ); MDC.put("traceId", "req-abc123"); executor.submit(() -> { log.info("this log carries traceId"); // ✅ 正常输出 traceId });

注意事项与进阶建议

该方案已覆盖绝大多数场景，但需注意几个细节：

• 不要在异步任务中长期持有 MDC 引用：快照是深拷贝（MDC.getCopyOfContextMap() 返回新 Map），但值本身仍是原始引用；若存的是可变对象，需自行 clone
• 配合 WebFilter 自动注入 traceId：在 Spring MVC 或 Servlet Filter 中解析请求头（如 X-Trace-ID）并写入 MDC，后续所有同步/异步日志自动携带
• 慎用于定时任务或长周期线程：若任务执行时间远超请求生命周期（如 5 分钟后才执行），traceId 可能已过期或语义失效，此时应结合业务生成新 ID
• 与 CompletableFuture 配合需额外处理：CF 默认使用 ForkJoinPool，不走自定义 executor；务必显式指定 supplyAsync(supplier, executor)

不复杂但容易忽略。只要在任务入口捕获、出口还原，MDC 就能稳稳跨线程跑起来。