MDC是Logback和Log4j2基于ThreadLocal实现的线程局部上下文机制，支持线程隔离的日志参数传递；需手动传递至子线程、Web请求中统一注入/清理、避免遗漏clear、正确配置日志格式输出。
MDC（Mapped Diagnostic Context）是 Logback 和 Log4j2 提供的线程局部上下文机制，它利用 ThreadLocal 为每个线程维护独立的键值对集合，从而在多线程环境下实现日志内容的线程级隔离。关键在于：MDC 的操作（如 put、get、clear）默认只影响当前线程，天然具备线程安全性，无需额外同步。
确保 MDC 在子线程中正确继承
主线程设置的 MDC 内容默认不会自动传递给新创建的线程（如线程池中的工作线程）。若不处理，子线程日志将丢失上下文（如 traceId、userId）。
- 使用支持 MDC 传递的线程池包装器，例如 Logback 自带的
LoggingEventAsyncAppender不适用此场景；更常用的是手动包装Runnable或使用org.slf4j.MDC的工具方法 - 推荐方式：在提交任务前捕获当前 MDC，构造新
Runnable并在执行前还原 - 示例代码：
Map<String, String> context = MDC.getCopyOfContextMap();
executor.submit(() -> {
try {
if (context != null) {
MDC.setContextMap(context);
}
// 执行业务逻辑
logger.info("This log carries MDC context");
} finally {
MDC.clear(); // 清理避免内存泄漏或污染后续任务
}
});在 Web 应用中统一注入和清理 MDC
典型场景是为每个 HTTP 请求生成唯一 traceId，并贯穿整个请求链路（含异步调用）。
- 在过滤器（Filter）或拦截器（Interceptor）中初始化 MDC：如
MDC.put("traceId", UUID.randomUUID().toString()) - 务必在请求结束时调用
MDC.clear()，否则 Tomcat 等容器复用线程会导致上下文残留 - 若使用 Spring WebFlux 或异步 Servlet，需结合
WebMvcConfigurer或AsyncHandlerInterceptor确保异步线程也能获取上下文
避免常见陷阱
MDC 使用简单，但几个细节容易引发问题：
sc-java-to-ts-interface
下载
将后端 Java 接口文档转换为前端 TypeScript 类型定义（interface / type）。输入：飞书文档、Spring Boot 接口文档、Swagger/OpenAPI、手写 API 文档等。输出：包含请求参数与响应结果的 .md 文件，含完整 JSDoc 注释。触发关键词：Java 转 TS、接口转换、生成前端类型、接口文档转 TypeScript、DTO/VO/BO 转 interface、后端文档转前端类型、生成接口类型、类型定义生成。
立即学习“Java免费学习笔记（深入）”；
- 忘记 clear()：尤其在线程池场景下，未清理的 MDC 会污染后续任务，导致日志混杂、排查困难
- 在 Lambda 中直接引用外部 MDC：Java 8 Lambda 捕获的是变量快照，而非实时 ThreadLocal，必须显式复制并设置
-
与异步框架集成不当：如使用 CompletableFuture，默认不继承 MDC；需用
CompletableFuture.supplyAsync(supplier, executor)配合自定义 executor，或手动 wrap supplier -
Log4j2 用户注意：其 MDC API 与 SLF4J 一致（
org.apache.logging.log4j.ThreadContext是等效实现），但需确认桥接器版本兼容，避免混用org.slf4j.MDC和ThreadContext
配合日志格式输出 MDC 字段
仅设置 MDC 不够，还需在日志配置中声明占位符，才能实际输出。
- Logback
logback-spring.xml示例：
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - [traceId:%X{traceId:-}, userId:%X{userId:-}] - %msg%n</pattern>
</encoder>
</appender>其中 %X{traceId:-} 表示取 key 为 traceId 的 MDC 值，:- 后为默认值（空字符串），避免未设置时输出 null
