MDC是日志框架提供的线程级上下文工具，底层基于ThreadLocal<Map<String, String>>实现；通过put/get/clear操作管理键值对，日志格式中用%X{key}引用，需在请求入口注入并在结束时清理以防污染。
MDC（Mapped Diagnostic Context）在 Java 日志中用于为每条日志附加上下文信息（如请求 ID、用户 ID），而底层核心依赖 ThreadLocal 实现线程隔离的上下文存储。它本身不是 JDK 原生类，而是 Logback/Log4j 等日志框架提供的工具，但其原理完全基于 ThreadLocal<Map<String, String>>。
ThreadLocal 是 MDC 的底层支撑
MDC 本质是一个静态的 ThreadLocal<Map<String, String>> 实例（Logback 中是 BasicMDCAdapter 内部维护的）。每次调用 MDC.put("key", "value")，实际是：
- 获取当前线程绑定的 Map（若无则新建并 set 进 ThreadLocal）
- 向该 Map 中插入键值对
- 日志输出时，Appender 从当前线程的 MDC Map 中读取字段，拼入日志格式（如
%X{traceId}）
手动用 ThreadLocal 模拟简易 MDC
不依赖日志框架，也能用 ThreadLocal 实现类似能力：
public class SimpleMDC {
private static final ThreadLocal<Map<String, String>> context =
ThreadLocal.withInitial(HashMap::new);
public static void put(String key, String value) {
context.get().put(key, value);
}
public static String get(String key) {
return context.get().get(key);
}
public static void clear() {
context.get().clear();
}
// 注意：必须显式清理，避免内存泄漏或上下文污染
public static void remove() {
context.remove();
}
}
使用时需确保在业务逻辑前后配对调用 put 和 remove（尤其在线程池场景下）。
立即学习“Java免费学习笔记（深入）”；
多线程/线程池场景下的关键问题
ThreadLocal 天然不传递，子线程无法继承父线程的 MDC 内容。常见解决方案有：
-
手动透传：在创建子线程或提交任务前，先
Map<String,String> parentCtx = MDC.getCopyOfContextMap()，然后在子线程开头调用MDC.setContextMap(parentCtx) -
装饰 Runnable/Callable：封装一个
MDCRunnable，构造时捕获当前 MDC 快照，执行时 restore；Spring 的ThreadPoolTaskExecutor支持设置taskDecorator自动完成此操作 -
使用支持 MDC 传递的组件：如 SLF4J + Logback 默认不传递，但可通过
logback-classic的AsyncAppender或第三方库（如log4j-mdc-traceid）增强；Web 场景中 Spring Boot 的WebMvcConfigurer可在拦截器中统一注入和清理
最佳实践要点
使用 MDC 时需注意：
- 每次请求入口（如 Filter、Interceptor、Controller 方法开始）放入关键字段（
traceId、userId） - 务必在请求结束或异常退出路径中调用
MDC.clear()或MDC.remove()—— 否则线程复用时会残留旧上下文 - 避免存放大对象或敏感信息（如密码、token 全文），仅存标识类字符串
- 异步调用链中，优先用标准追踪方案（如 OpenTelemetry + Sleuth）替代纯 MDC，更利于跨服务传递
