TransmittableThreadLocal

TransmittableThreadLocalTransmittableThreadLocal （简称 TTL）是阿里巴巴开源的一个线程本地变量传递工具，解决了 JDK 原生ThreadLocal在线程池场景下无法传递上下文的问题。

它是对InheritableThreadLocal的增强，特别适用于分布式系统中线程池复用场景下的上下文传递。

TransmittableThreadLocal主要解决以下问题：

        1.原生ThreadLocal无法在父线程与子线程间传递数据

        2.InheritableThreadLocal只能在子线程创建时复制数据，无法应对线程池的线程复用

        3.支持在使用线程池时，自动传递上下文信息

示例

        下面是一个基于 Spring Boot 的使用示例，展示如何在线程池中传递上下文：

<!-- 在pom.xml中添加TTL依赖 -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>transmittable-thread-local</artifactId>
    <version>2.14.2</version> <!-- 使用最新稳定版本 -->
</dependency>

import com.alibaba.ttl.TransmittableThreadLocal;
import com.alibaba.ttl.TtlRunnable;

import java.util.UUID;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

/**
 * 基于TransmittableThreadLocal的追踪上下文
 */
public class TraceContext {
    // 使用TTL替代原生ThreadLocal
    private static final TransmittableThreadLocal<String> TRACE_ID = new TransmittableThreadLocal<>();

    // 设置追踪ID
    public static void setTraceId(String traceId) {
        TRACE_ID.set(traceId);
    }

    // 获取追踪ID
    public static String getTraceId() {
        return TRACE_ID.get();
    }

    // 生成新的追踪ID
    public static String generateTraceId() {
        return UUID.randomUUID().toString().replace("-", "");
    }

    // 清除上下文
    public static void clear() {
        TRACE_ID.remove();
    }

    // 示例：在线程池中使用TTL
    public static void main(String[] args) {
        // 创建线程池
        ExecutorService executor = Executors.newFixedThreadPool(1);
        
        // 父线程设置上下文
        TraceContext.setTraceId(generateTraceId());
        System.out.println("父线程TraceId: " + TraceContext.getTraceId());
        
        // 提交任务到线程池，使用TtlRunnable包装
        executor.submit(TtlRunnable.get(() -> {
            // 子线程中可以获取到父线程的上下文
            System.out.println("子线程TraceId: " + TraceContext.getTraceId());
        }));
        
        // 清理资源
        executor.shutdown();
        TraceContext.clear();
    }
}

解析

1.线程池上下文传递

            通过TtlRunnable和TtlCallable包装任务，实现线程池环境下的上下文传递，解决了线程复用导致的上下文丢失问题。

2.与原生 API 兼容

            TransmittableThreadLocal继承自InheritableThreadLocal，可以无缝替换ThreadLocal，原有代码只需修改声明即可。

3.性能优化

            采用延迟复制机制，只有当线程池执行任务时才复制上下文，减少不必要的性能开销。

4.集成方式灵活

    手动包装：使用TtlRunnable.get()和TtlCallable.get()

    自动包装：通过 Java Agent 实现线程池的自动增强，无需修改代码

应用场景

    分布式追踪系统：传递 Trace ID 和 Span ID

    日志系统：在多线程环境下关联同一请求的日志

    权限认证：传递用户身份信息到线程池任务中

    微服务调用：在服务间传递上下文信息

注意事项

    必须使用 TTL 提供的包装类（TtlRunnable/TtlCallable）包装提交到线程池的任务

    线程池执行完任务后，建议清理上下文信息

    在使用 Java Agent 自动增强时，需要注意与其他 Agent 的兼容性

    避免存储过大的对象，以免影响性能

TransmittableThreadLocal已被广泛应用于阿里内部系统和众多开源项目中，是解决线程池上下文传递问题的首选方案。