logback 的 mdc（mapped diagnostic context）需通过 `
在 Logback 中，MDC.put("key", "value") 确实能成功将键值对存入当前线程上下文（可通过 MDC.get("key") 验证），但能否在日志中显示，取决于日志输出配置是否支持 MDC 变量解析。
关键误区在于：许多开发者误以为 <encoder> 的 <pattern> 支持完整的 MDC 占位符语法（如 %X{ApigeeId}），但实际上——Logback 仅在 <layout>（尤其是 PatternLayout）中才完整支持 %X{key}、%X 等 MDC 相关转换词。而 <encoder> 在较新版本 Logback（1.3+）中主要用于字节流编码（如 UTF-8 编码控制），其内部 PatternLayoutEncoder 虽可接受 <pattern>，但必须显式嵌套在 <layout> 标签下才能启用完整的转换词解析能力，包括 MDC、异常堆栈、时间格式化等高级功能。
✅ 正确配置方式（推荐）：
<appender name="Console" class="ch.qos.logback.core.ConsoleAppender">
<layout class="ch.qos.logback.classic.PatternLayout">
<pattern>%d [%X{ApigeeId:-N/A}] [%X{BasePath:-N/A}] %-5level %-50logger{40} - %message%n</pattern>
</layout>
</appender>⚠️ 注意事项：
- <layout> 必须指定 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{...} 写在 <encoder><pattern> 下——应移至 <layout><pattern> 内，并确保使用 PatternLayout 类型。配置修正后，无需修改业务代码，即可实时生效。
