在 java 中,使用 traceid 关联调用链路的核心做法是:在请求入口处生成唯一的 traceid,并通过 mdc(mapped diagnostic context)将其存入当前线程的上下文中。随后,配置日志框架(如 logback 或 log4j2)的 patternlayout,将 %x{traceid} 占位符写入日志输出格式。这样,所有经过该线程处理的日志都会自动携带相同的 traceid,从而实现链路的串联与追踪。

如何配置日志模板以输出 TraceId
要让日志文件真正显示 TraceId,必须修改日志输出的 Pattern 配置。Logback 和 Log4j2 都支持通过 %X{key} 语法读取 MDC 中的数据。你需要找到应用的日志配置文件(通常是 logback-spring.xml 或 log4j2-spring.xml),在 标签中加入 %X{traceId}。配置完成后,每次打印日志时,日志框架会自动从当前线程的 MDC 中查找名为 traceId 的值并替换到对应位置。如果 MDC 中没有该值,则输出为空或默认标记,因此务必确保在请求入口处正确设置。

<configuration><appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"><encoder><pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %X{traceId} - %msg%n</pattern></encoder></appender><root level="INFO"><appender-ref ref="STDOUT"></appender-ref></root></configuration>
上述配置定义了控制台输出格式。其中 %X{traceId} 是关键部分。当应用启动并处理请求时,只要 MDC 中设置了 traceId,控制台打印的每一行日志都会在时间戳和日志级别之后、类名之前显示该 ID。这有助于开发者在海量日志中快速筛选出属于同一请求的所有日志片段。
如何在 Spring Boot 中拦截请求并注入 TraceId
在 Spring Boot 应用中,最标准的做法是使用 HandlerInterceptor 或 Filter 来统一处理 TraceId 的生成与清理。推荐使用 HandlerInterceptor,因为它能更精细地控制 Web 请求的生命周期。我们需要实现一个拦截器,在 preHandle 方法中生成 UUID 并存入 MDC,在 afterCompletion 方法中清除 MDC 以防止内存泄漏或线程池复用导致的上下文污染。最后,将该拦截器注册到 Spring MVC 的配置中,使其对所有 URL 生效。

import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.UUID;
@Component
public class TraceIdInterceptor implements HandlerInterceptor {
private static final String TRACE_ID_KEY = "traceId";
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
// 生成唯一 TraceId
String traceId = UUID.randomUUID().toString().replace("-", "");
// 存入 MDC
MDC.put(TRACE_ID_KEY, traceId);
return true;
}
@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
// 请求结束后清除 MDC,防止线程复用导致数据串扰
MDC.remove(TRACE_ID_KEY);
}
}
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class WebConfig implements WebMvcConfigurer {
private final TraceIdInterceptor traceIdInterceptor;
public WebConfig(TraceIdInterceptor traceIdInterceptor) {
this.traceIdInterceptor = traceIdInterceptor;
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(traceIdInterceptor)
.addPathPatterns("/**");
}
}
这段代码展示了完整的拦截器实现与注册过程。TraceIdInterceptor 在请求到达控制器之前执行,生成一个去除连字符的 UUID 字符串,并通过 MDC.put 绑定到当前线程。关键点在于 afterCompletion 方法,它确保了无论请求成功与否,MDC 中的 traceId 都会被移除。这是防止 Tomcat 等容器线程池复用线程时发生日志 ID 错乱的关键步骤。注册类 WebConfig 通过构造器注入拦截器实例,并将其应用到所有路径 /**。
异步线程中如何传递 TraceId
当业务逻辑涉及异步执行(如使用 @Async 或自定义线程池)时,主线程 MDC 中的 TraceId 不会自动传递给子线程。这是因为 MDC 基于 ThreadLocal 实现,而新创建的线程拥有独立的 ThreadLocal 存储。为了解决这个问题,需要在提交异步任务前,手动捕获主线程的 MDC 上下文,并在子线程执行初期将其恢复。通常的做法是创建一个包装类或使用装饰器模式,在 Runnable 或 Callable 的 run 方法中先复制 MDC 数据,执行完毕后清理。
import org.slf4j.MDC;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;
import java.util.Map;
@Service
public class AsyncService {
@Async
public void processAsync() {
// 在异步任务开始时,手动获取父线程的 MDC 并放入当前线程
Map<string string> mdcContextMap = MDC.getCopyOfContextMap();
if (mdcContextMap != null) {
MDC.setContextMap(mdcContextMap);
} else {
// 如果没有父上下文,可以选择生成新的或忽略
MDC.put("traceId", "ASYNC-" + System.currentTimeMillis());
}
try {
// 实际业务逻辑
System.out.println("Processing in async thread with traceId: " + MDC.get("traceId"));
} finally {
// 清理当前线程的 MDC
MDC.clear();
}
}
}</string>
在 processAsync 方法中,首先调用 MDC.getCopyOfContextMap() 获取主线程的上下文快照。如果存在快照,则通过 MDC.setContextMap() 将其应用到当前异步线程。这保证了异步任务产生的日志依然包含原始的 TraceId。最后,在 finally 块中调用 MDC.clear() 清理当前线程的上下文,避免线程池复用时的残留数据影响后续任务。这种手动传递的方式虽然增加了代码复杂度,但是保证分布式链路追踪完整性的必要手段。
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南











