MDC+Filter/Interceptor实现用户信息日志追踪：3步解决链路跟踪难题

首页

科技数码

热心网友

转载

2025-12-02

本文将通过Filter（过滤器）和Interceptor（拦截器）结合日志框架的MDC机制，详细讲解如何自动注入用户信息并实现全链路日志跟踪。

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

前言

在分布式系统或复杂业务架构中，日志是排查问题、追踪流程的关键工具。然而系统默认的日志输出往往缺少用户维度信息，导致问题发生时难以快速定位具体用户的操作链路。下面将详细介绍如何利用Filter或Interceptor与日志框架的MDC协作，实现用户信息的自动注入与全链路跟踪。

原理解析

要实现用户信息追踪，首先需要理解三个核心技术组件的作用与协作逻辑：MDC、Filter和Interceptor。

MDC：日志上下文的存储容器

MDC是SLF4J及Logback、Log4j2等日志框架提供的上下文工具，本质上是通过ThreadLocal实现的线程级键值对存储容器。其核心功能包括：

在请求处理线程中保存临时上下文信息（如用户ID、用户名、请求ID等）；日志输出时自动从MDC提取配置的键值，无需在每处日志打印代码中手动传入用户信息；线程结束后自动清理上下文，避免内存泄漏（需手动确保清理逻辑）。

MDC核心API（以SLF4J为例）：

// 向MDC存入键值对（如用户ID）
MDC.put("userId", "user_123456");
// 从MDC获取值
String userId = MDC.get("userId");
// 清空当前线程的MDC上下文（关键，必须执行）
MDC.clear();

Filter与Interceptor：请求链路的拦截器

图片

Filter和Interceptor都用于拦截HTTP请求，在处理前后执行自定义逻辑（如权限校验、参数预处理），这是注入MDC上下文的最佳切入点。

实践方案

方案1：基于Filter+MDC实现

自定义MDC过滤器

/**
 * 基于Filter的MDC用户信息注入过滤器
 */
public class MdcUserFilter extends OncePerRequestFilter {
    // 定义MDC中用户信息的键（需与日志配置一致）
    private static final String MDC_USER_ID = "userId";
    private static final String MDC_USER_NAME = "userName";
    
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
            throws ServletException, IOException {
        try {
            // 1.从请求头提取用户信息（实际项目需替换为Token解析、Session获取等逻辑）
            String userId = request.getHeader("X-User-Id");
            String userName = request.getHeader("X-User-Name");
            
            // 2.注入MDC（若用户未登录，可存入默认值如"unknown"）
            MDC.put(MDC_USER_ID, userId != null ? userId : "unknown");
            MDC.put(MDC_USER_NAME, userName != null ? userName : "unknown");
            
            // 3.继续执行请求链路（进入Controller层）
            filterChain.doFilter(request, response);
        } finally {
            // 4.关键：请求结束后清理MDC，避免线程复用导致上下文污染（线程池场景必做）
            MDC.clear();
        }
    }
}

步骤2：注册Filter到Spring容器

@Configuration
public class FilterConfig {
    @Bean
    public FilterRegistrationBean mdcUserFilterRegistration() {
        FilterRegistrationBean registrationBean = new FilterRegistrationBean<>();
        registrationBean.setFilter(new MdcUserFilter());
        // 拦截所有请求
        registrationBean.addUrlPatterns("/*");
        // 设置过滤器优先级（值越小优先级越高，确保先于其他业务过滤器执行）
        registrationBean.setOrder(Ordered.HIGHEST_PRECEDENCE);
        return registrationBean;
    }
}

方案2：基于Interceptor+MDC实现

步骤1：自定义MDC拦截器

/**
 * 基于Interceptor的MDC用户信息注入拦截器
 */
public class MdcUserInterceptor implements HandlerInterceptor {
    private static final String MDC_USER_ID = "userId";
    private static final String MDC_USER_NAME = "userName";
    
    /**
     * 请求处理前执行：注入MDC
     */
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // 1.提取用户信息（逻辑与Filter一致，可复用工具类）
        String userId = request.getHeader("X-User-Id");
        String userName = request.getHeader("X-User-Name");
        
        // 2.注入MDC
        MDC.put(MDC_USER_ID, userId != null ? userId : "unknown");
        MDC.put(MDC_USER_NAME, userName != null ? userName : "unknown");
        
        // 返回true：继续执行后续链路（如Controller）
        returntrue;
    }
    
    /**
     * 请求完成后执行（无论是否抛异常）：清理MDC
     */
    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        // 关键：清理MDC，避免线程池上下文污染
        MDC.clear();
    }
}

步骤2：注册Interceptor到SpringMVC

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new MdcUserInterceptor())
                // 拦截所有请求
                .addPathPatterns("/**")
                // 排除无需拦截的路径（如登录接口、静态资源等）
                .excludePathPatterns("/api/login", "/static/**", "/error");
    }
}

配置日志输出MDC信息

%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - userId:%X{userId} userName:%X{userName} - %msg%n UTF-8 logs/app.log logs/app.%d{yyyy-MM-dd}.log 30 %d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - userId:%X{userId} userName:%X{userName} - %msg%n UTF-8

线程池场景下的MDC传递

手动传递MDC上下文

public class AsyncMdcDemo {
    // 初始化线程池
    private static final ExecutorService executorService = Executors.newFixedThreadPool(5);
    public void doAsyncTask() {
        // 1.获取当前线程的MDC上下文（包含用户信息）
        Map mdcContext = MDC.getCopyOfContextMap();
        
        // 2.提交异步任务到线程池
        executorService.submit(() -> {
            try {
                // 3.子线程中注入MDC上下文
                if (mdcContext != null) {
                    MDC.setContextMap(mdcContext);
                }
                
                // 4.异步业务逻辑（日志会自动包含用户信息）
                log.info("执行异步任务：处理用户订单");
            } finally {
                // 5.子线程结束后清理MDC
                MDC.clear();
            }
        });
    }
}

封装线程池（避免重复代码）

// Spring异步任务装饰器：自动传递MDC public class MdcTaskDecorator implements TaskDecorator { @Override public Runnable decorate(Runnable runnable) { // 获取当前线程MDC上下文 Map mdcContext = MDC.getCopyOfContextMap(); return () -> { try { // 子线程注入MDC if (mdcContext != null) { MDC.setContextMap(mdcContext); } runnable.run(); } finally { MDC.clear(); } }; } } // 配置Spring异步线程池（使用装饰器） @Configuration @EnableAsync public class AsyncConfig { @Bean public Executor asyncExecutor() { ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); executor.setCorePoolSize(5); executor.setMaxPoolSize(10); executor.setQueueCapacity(25); // 设置MDC装饰器 executor.setTaskDecorator(new MdcTaskDecorator()); executor.initialize(); return executor; } }