ThreadLocal 本身不能直接实现全链路日志追踪，但可作为本地上下文容器配合拦截器透传 traceId，需在请求开始时生成/解析、结束时清理，并通过 MDC 集成日志框架，跨线程场景需用 TTL 或手动传递。
ThreadLocal 本身不能直接实现全链路日志追踪，但它可以作为本地上下文容器，配合拦截器（如 Spring 的 HandlerInterceptor 或 WebMvcConfigurer）在单次请求的线程内透传唯一 traceId，是实现轻量级全链路日志追踪的关键一环。
1. 用 ThreadLocal 存储 traceId
定义一个工具类，用 ThreadLocal 持有当前请求的唯一标识：
public class TraceIdUtil {
private static final ThreadLocal<string> TRACE_ID_HOLDER = ThreadLocal.withInitial(() ->
UUID.randomUUID().toString().replace("-", "")
);
<pre class="brush:php;toolbar:false;">public static String getTraceId() {
return TRACE_ID_HOLDER.get();
}
public static void setTraceId(String traceId) {
TRACE_ID_HOLDER.set(traceId);
}
public static void clear() {
TRACE_ID_HOLDER.remove();
}
}
注意：每次请求开始必须生成或解析 traceId，结束必须调用 clear()，否则线程复用（如 Tomcat 线程池）会导致 traceId 串扰。
2. 在拦截器中注入和清理 traceId
实现 HandlerInterceptor，在请求进入时生成/提取 traceId，响应返回前清理：
@Component
public class TraceIdInterceptor implements HandlerInterceptor {
<pre class="brush:php;toolbar:false;">@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
// 优先从 Header 中读取上游传来的 traceId（便于跨服务传递）
String traceId = Optional.ofNullable(request.getHeader("X-Trace-ID"))
.filter(s -> !s.trim().isEmpty())
.orElseGet(UUID::randomUUID)
.toString()
.replace("-", "");
TraceIdUtil.setTraceId(traceId);
// 可选：把 traceId 写回响应头，方便前端或下游服务继续传递
response.setHeader("X-Trace-ID", traceId);
return true;
}
@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
TraceIdUtil.clear(); // 必须清理！
}
}
注册拦截器时注意顺序，确保它在最外层生效：
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new TraceIdInterceptor()).addPathPatterns("/**");
}
}
3. 日志框架自动打印 traceId
以 Logback 为例，在 logback-spring.xml 中使用 %X{traceId} 占位符，并通过 MDC（Mapped Diagnostic Context）绑定 ThreadLocal 值：
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"><encoder><pattern>%d{HH:mm:ss.SSS} [%X{traceId}] [%thread] %-5level %logger{36} - %msg%n</pattern></encoder></appender>再写一个 Logback 的 Filter 或利用 LoggerContext 初始化时绑定：
@Component
public class TraceIdMdcFilter implements Filter {
@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {
try {
MDC.put("traceId", TraceIdUtil.getTraceId());
chain.doFilter(request, response);
} finally {
MDC.remove("traceId"); // 清理 MDC，避免内存泄漏
}
}
}
或者更推荐：在拦截器的 preHandle 中调用 MDC.put("traceId", ...)，afterCompletion 中 MDC.remove("traceId") —— 和 ThreadLocal 生命周期保持一致。
4. 跨线程场景需手动传递（如异步、线程池）
ThreadLocal 不会自动跨线程继承。若业务中有 @Async、CompletableFuture、自定义线程池等，需显式传递 traceId：
- 使用
ThreadPoolTaskExecutor时，包装Runnable，拷贝当前 MDC + ThreadLocal 到子线程 - 用
TransmittableThreadLocal（阿里 TTL 库）替代原生 ThreadLocal，可自动传递上下文 - 在 CompletableFuture 异步块开头手动
MDC.put("traceId", ...)
例如（TTL 方式）：
// 替换 ThreadLocal 为 TransmittableThreadLocal
private static final TransmittableThreadLocal<string> TRACE_ID_HOLDER =
new TransmittableThreadLocal();
</string>这样连 supplyAsync 都能自动继承 traceId，无需额外处理。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
