Spring Boot + Logback MDC 深度解析：实现全链路日志追踪

1. MDC 核心概念与价值

MDC (Mapped Diagnostic Context) 是 SLF4J/Logback 提供的线程级上下文存储机制，在 Spring Boot 应用中主要解决：

• 请求链路追踪：自动在日志中嵌入 traceId、userId 等关键信息
• 日志结构化：无需手动拼接上下文，提升日志可读性和可分析性
• 异步上下文传递：解决线程池场景下的上下文丢失问题

2. Spring Boot 集成 Logback MDC 完整配置

2.1 基础依赖（无需额外引入）

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- 默认包含 logback + slf4j -->

2.2 Logback 配置（logback-spring.xml）

<configuration>
    <!-- 控制台输出，携带MDC信息 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>
                %d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} 
                [traceId=%X{traceId}, userId=%X{userId}] - %msg%n
            </pattern>
        </encoder>
    </appender>

    <!-- 文件输出，JSON结构化日志 -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>logs/app.log</file>
        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
            <includeMdcKeyName>traceId,userId</includeMdcKeyName>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="FILE"/>
    </root>
</configuration>

3. 核心代码实现

3.1 拦截器自动注入 traceId

@Component
public class MdcInterceptor implements HandlerInterceptor {
    
    @Override
    public boolean preHandle(HttpServletRequest request, 
                           HttpServletResponse response, 
                           Object handler) {
        // 生成唯一traceId
        String traceId = UUID.randomUUID().toString().replace("-", "");
        MDC.put("traceId", traceId);
        
        // 从JWT或Session获取用户信息
        String userId = extractUserId(request);
        MDC.put("userId", userId);
        
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, 
                              HttpServletResponse response, 
                              Object handler, Exception ex) {
        // 必须清理防止内存泄漏
        MDC.clear();
    }
}

3.2 注册拦截器

@Configuration
public class WebConfig implements WebMvcConfigurer {
    
    @Autowired
    private MdcInterceptor mdcInterceptor;
    
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(mdcInterceptor)
                .addPathPatterns("/**");
    }
}

3.3 异步线程池上下文传递

@Configuration
public class AsyncConfig {
    
    @Bean
    public Executor asyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor() {
            @Override
            public void execute(Runnable task) {
                // 传递MDC上下文
                Map<String, String> context = MDC.getCopyOfContextMap();
                super.execute(() -> {
                    try {
                        if (context != null) {
                            MDC.setContextMap(context);
                        }
                        task.run();
                    } finally {
                        MDC.clear();
                    }
                });
            }
        };
        executor.initialize();
        return executor;
    }
}

4. 高级场景解决方案

4.1 Feign 客户端透传 traceId

@Bean
public RequestInterceptor feignRequestInterceptor() {
    return template -> {
        String traceId = MDC.get("traceId");
        if (traceId != null) {
            template.header("X-Trace-Id", traceId);
        }
    };
}

4.2 RabbitMQ 消费者获取上下文

@RabbitListener(queues = "demo.queue")
public void handleMessage(Message message, @Header("X-Trace-Id") String traceId) {
    if (traceId != null) {
        MDC.put("traceId", traceId);
    }
    // 业务处理...
    MDC.clear();
}

5. 关键注意事项

1. 内存泄漏风险

   • 必须使用 try-finally 确保 MDC.clear()
   • 特别关注线程池场景

2. 性能影响

   • MDC 操作基于 ThreadLocal，单次操作约 0.01ms
   • 避免在高频循环中频繁修改MDC

3. 日志规范建议

   // 反模式：手动拼接已有MDC字段
   log.info("User {} operated", MDC.get("userId")); 
   
   // 正解：直接使用pattern中的%X
   log.info("User operated"); 
   

6. 性能测试数据

测试环境：Spring Boot 2.7 + 4核8G服务器，JMeter 500并发

总结

通过合理使用 MDC，可实现：

• 日志与业务逻辑解耦
• 全链路请求追踪
• 结构化日志分析
• 线程安全的上下文管理