《Spring 中上下文传递的那些事儿》 Part 1：ThreadLocal、MDC、TTL 原理与实践

📝 Part 1：ThreadLocal、MDC、TTL 原理与实践

在 Java 应用开发中，线程上下文信息传递是一个非常常见但又容易被忽视的问题。尤其是在多线程或异步编程场景下，如何保证当前请求的上下文（如用户身份、traceId、租户信息等）能够在整个调用链中正确传递，是构建稳定系统的关键。

本文将带你深入理解三种最常见的上下文管理方案：ThreadLocal、MDC 和 TTL，并结合 Spring 框架和实际业务场景进行详细讲解。

一、ThreadLocal —— 最基础的线程本地变量

1. 原理简介

ThreadLocal 是 Java 提供的一个线程级别的本地变量存储机制。每个线程都有自己的独立副本，互不干扰。

public class UserContext {
    private static final ThreadLocal<String> currentUser = new ThreadLocal<>();

    public static void setCurrentUser(String user) {
        currentUser.set(user);
    }

    public static String getCurrentUser() {
        return currentUser.get();
    }

    public static void clear() {
        currentUser.remove();
    }
}

2. 使用场景

• 请求拦截器中设置用户信息。
• 日志记录时携带用户信息。
• 在 Service 层或 DAO 层复用当前用户信息。

3. 注意事项

• 无法跨线程使用：在线程池中执行任务时，子线程无法继承主线程的值。
• 需要手动清理资源，避免内存泄漏。

4. Spring 整合建议

• 可以封装为一个工具类，在 Controller 层通过拦截器设置，在 Service 层使用。
• 推荐配合 @Component 或 @Service 注入上下文逻辑。

二、MDC（Mapped Diagnostic Context）—— 日志追踪利器

1. 原理简介

MDC 是日志框架（如 Logback、Log4j）提供的一个线程上下文机制，用于在日志中打印诊断信息（如 traceId、userId 等）。

import org.slf4j.MDC;

MDC.put("userId", "123");
log.info("This log contains userId: {}", MDC.get("userId"));

2. 使用场景

• 链路追踪中的 traceId、spanId 传递。
• 用户标识、租户标识等信息写入日志。
• 结合 AOP 或 Filter 实现统一日志上下文注入。

3. 注意事项

• 同样基于线程局部变量，无法自动跨线程传递。
• 日志内容依赖日志框架配置，不具备业务逻辑上下文能力。

4. Spring 整合建议

• 在全局拦截器或过滤器中设置关键字段（如 traceId）。
• 使用 @Aspect 切面统一打印上下文信息。
• 推荐配合 Sleuth + Zipkin 实现完整的分布式追踪。

示例：日志模板配置（logback-spring.xml）

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg [userId=%X{userId}, traceId=%X{traceId}]%n</pattern>
        </encoder>
    </appender>

    <root level="info">
        <appender-ref ref="STDOUT"/>
    </root>
</configuration>

三、TTL（TransmittableThreadLocal）—— 支持线程池的上下文传递

1. 原理简介

TTL（TransmittableThreadLocal）是 Alibaba 开源的一个增强版 ThreadLocal，解决了线程池中上下文丢失的问题。它通过装饰 Runnable 和 Callable 来实现上下文的复制与恢复。

GitHub 地址：https://github.com/alibaba/transmittable-thread-local

<!-- Maven 引入 -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>transmittable-thread-local</artifactId>
    <version>2.12.1</version>
</dependency>

TransmittableThreadLocal<String> context = new TransmittableThreadLocal<>();
context.set("value");

ExecutorService executor = TtlExecutors.getTtlExecutorService(Executors.newFixedThreadPool(2));

executor.submit(() -> {
    System.out.println(context.get()); // 输出 value
});

2. 使用场景

• 使用线程池处理异步任务时需要上下文。
• 微服务内部多线程并发调用。
• 避免因线程复用导致上下文混乱。

3. 优点

• 完全兼容原生 ThreadLocal。
• 支持线程池、CompletableFuture、ScheduledExecutorService 等。
• 可以与 MDC 联合使用，解决日志上下文丢失问题。

4. Spring 整合建议

• 替换所有 ThreadLocal 为 TransmittableThreadLocal。
• 包装线程池：使用 TtlExecutors.getTtlExecutorService()。
• 配合自定义注解 + AOP 实现上下文自动注入。

四、综合对比表

五、推荐组合方案（适用于微服务）

六、结语

在 Spring 应用中，合理选择上下文传递机制对于构建稳定、可维护的系统至关重要。不同场景应采用不同的策略：

• 单线程同步操作：使用 ThreadLocal 或 MDC。
• 多线程异步操作：优先考虑 TTL。
• 分布式链路追踪：结合 Sleuth + Zipkin。

如果你正在构建的是一个典型的微服务架构项目，强烈建议使用 TTL + MDC + Sleuth 的组合，以实现优雅的上下文管理和日志追踪体系。

📌 参考链接

• TransmittableThreadLocal GitHub
• Spring Boot Logging with MDC