如何在 Logback 中正确使用 MDC 实现日志上下文变量注入

logback 的 mdc（mapped diagnostic context）需通过 `` 配置而非 `` 中的 `` 才能正确解析 `%x{key}` 占位符，否则日志中对应字段将为空。

在 Logback 中，MDC.put("key", "value") 确实能成功将键值对存入当前线程上下文（可通过 MDC.get("key") 验证），但能否在日志中显示，取决于日志输出配置是否支持 MDC 变量解析。

关键误区在于：许多开发者误以为 的 支持完整的 MDC 占位符语法（如 %X{ApigeeId}），但实际上——Logback 仅在 （尤其是 PatternLayout）中才完整支持 %X{key}、%X 等 MDC 相关转换词。而 在较新版

本 Logback（1.3+）中主要用于字节流编码（如 UTF-8 编码控制），其内部 PatternLayoutEncoder 虽可接受 ，但必须显式嵌套在 标签下才能启用完整的转换词解析能力，包括 MDC、异常堆栈、时间格式化等高级功能。

✅ 正确配置方式（推荐）：

  
    %d [%X{ApigeeId:-N/A}] [%X{BasePath:-N/A}] %-5level %-50logger{40} - %message%n
  

⚠️ 注意事项：

• 必须指定 class="ch.qos.logback.classic.PatternLayout"（经典版布局，专为 Logger 设计）；
• 使用 %-X{key:-default} 可设置默认值（如 :-N/A），避免空字段影响日志可读性；
• MDC 是线程绑定的，务必在请求入口（如 Spring 拦截器、Servlet Filter 或 WebMvcConfigurer）中 put，并在请求结束时调用 MDC.clear() 或 MDC.remove("key")，防止线程复用导致脏数据（尤其在 Tomcat 线程池场景下）；
• 若使用异步日志（如 AsyncAppender），需确保 includeCallerData="false" 且 discardingThreshold="0" 配合 MDC.put()，或改用 AsyncAppender + MDCFilter 等方案保障上下文传递。

总结：MDC 值未出现在日志中，99% 是因配置层级错误。请立即检查 logback.xml 中是否将 %X{...} 写在 下——应移至 内，并确保使用 PatternLayout 类型。配置修正后，无需修改业务代码，即可实时生效。