用ThreadLocal与Deque构建轻量级调用链上下文

聊个我在排查线上问题时的真实场景：一个下单接口偶发变慢，慢到用户投诉那种。我打开日志按请求ID去捞，发现只有入口和出口两条日志，中间嵌套调用的那些业务日志因为当时没打满，全是缺口。那会儿我就想，要是能有一个“当前线程正在执行的方法调用链”随时打印出来该多好。后来翻到Spring Insight的设计，发现它就是用ThreadLocal套一个Deque，硬生生做出了一个线程专属的调用栈，把上下文管理这个问题解决得非常干净。

这篇博文不打算讲完整的APM产品设计，而是把这个核心数据结构拆开揉碎：ThreadLocal怎么保证每个线程拿到自己的栈，Deque怎么顶出一个优雅的进出栈操作，以及为什么这套组合在Spring这类大量使用线程池的容器场景下仍然能稳得住。适合正被日志链路不完整、嵌套调用没法溯源、或者想自己撸一个轻量级调用链组件的同学参考。基线是Java 8以后的环境，代码可以直接抄去改。

1. 为什么需要“线程专属的调用栈”

1.1 一次排查慢接口的切身经历

那个接口的处理流程我到现在还记得：入口Controller拿到参数后，先做了一堆参数组装，然后调用一个本地Service，Service里又依次调了数据库、缓存、外部HTTP接口，最后还有个线程池异步往消息中心发一条通知。慢的时候，从接到请求到返回用了5秒。日志里的入口打点和出口打点都在，但中间具体是哪一步慢，完全没有单独记录。而且异步通知那段跑在另一个线程，日志时间戳和requestId都没有对齐，排查起来只能靠猜。

后来我给Service里的每个子方法都加了切面计时，但那个接口的改动牵连很广，光是完善日志就折腾了半天，上线后还得等线上重现问题才能验证。这种“等现场”的体验非常被动。更好的办法是在运行时直接取到当前线程的执行链：不用等事情发生后再推断，而是随时可以问“此刻这个线程在干什么”。这正是调用栈的价值。

其实JVM自己就维护着一套真实的调用栈，每个线程在任意一个时刻都有自己的一组栈帧。问题在于，JVM栈帧里只有类名、方法名、字节码行号这些东西，你想额外塞业务ID、参数摘要、耗时统计进去是塞不进去的。所以我们需要在应用层自己做一个“虚拟线程栈”，把运行时希望追踪的信息挂进去。

1.2 线程、异步与调用链的三角关系

在Java服务端程序里，一个请求的处理绝不会是一条直线。Spring MVC默认每个请求占一个线程，线程内再嵌套调用其他方法，这还好；当你不经意间用线程池提交了一个异步任务，调用链就分裂了。

ThreadLocal能解决主线程内部的上下文传递问题，因为它绑定的是“值所属的线程”。同一个线程里，你在任意深度拿到的都是同一个对象。这正是我们构建调用栈的基础：入栈、出栈都发生在线程内，天然顺序一致。

但如果线程之间要传上下文，就要格外小心。子线程不会自动继承父线程的ThreadLocal内容，即使用了InheritableThreadLocal，它也只在new Thread那一刻拷贝一次。线程池复用的线程更麻烦，一次拷贝之后，后续跑什么任务都串着同一个旧值。这也是很多调用链组件把ThreadLocal当成第一层存储、再配合任务包装类做二次传递的原因。

1.3 Spring Insight 的上下文管理给了我什么启发

Spring Insight是Spring Source在收购Hyperic之后推出的应用性能管理产品，核心思路是在请求进入时构建一棵Trace树，把每次方法调用、SQL查询、HTTP远程调用都挂到树上。它始终要解决的问题是：在任一个执行节点上，如何知道它属于哪个请求、哪个父节点延伸出来的。

落到单线程内部，树的一个分支就是一截调用栈。你不需要把整棵树放在一个大Map里全局共享，你只需要在每个线程内部维护一条从根到当前节点的链，而这条链最直接的容器就是栈。所以ThreadLocal + Deque实际上是Spring Insight这类APM的微观实现基石之一。

我们不必复刻整个APM，只要把这个栈模型提取出来，能解决自己的埋点和链路可视化问题就够了。下面这一步一步讲。

2. 设计拆解：ThreadLocal 和 Deque 为什么是一对好搭档

2.1 ThreadLocal 的底层存取模型，getMap 到底返回了什么

先打破一个常见误区：ThreadLocal并不是直接把值存在ThreadLocal对象里，而是每个Thread对象内部都有一张名为threadLocals的map，ThreadLocal对象只是这张map的“key”。

ThreadLocal.get()的执行流程大致是：获取当前线程t，调用getMap(t)拿到t.threadLocals这个ThreadLocalMap；如果map不为null，就用当前ThreadLocal作为key去查Entry；查不到或者map本身就是null，就进入setInitialValue路径，调用initialValue()得到初始值，再通过createMap或set写入。

getMap为什么在源码里单独提一个方法呢？因为ThreadLocalMap是定义在ThreadLocal内部的静态内部类，而getMap方法的作用仅仅是包一层：“我要拿当前线程的threadLocals字段”。它的访问范围限定在包内和子类，业务代码不能直接调用，但看源码时它是一个高频出现的入口。

补一个关键细节：ThreadLocalMap解决哈希冲突用的不是链地址法，而是开放地址法中的线性探测。对象会直接存放在一个Entry数组里，每个Entry的key是对ThreadLocal的WeakReference。为什么要用黄金分割数0x61c88647增量生成threadLocalHashCode？就是为了让各个new出来的ThreadLocal在数组里分布得足够均匀，减少线性探测的长度。

理解了这一点，再看网上经常出现的“ThreadLocal getMap为null”问题就会明白：只要某个线程从未往任何ThreadLocal里写过值，它的threadLocals字段就还是null，这是完全正常的初始状态。在线程池里，一个线程想要有非null的map，至少得被某个ThreadLocal赋值过。所以排查问题的时候，别一看到null就慌。

2.2 为什么选 Deque，而不是 Stack 或 ArrayList

构建调用栈，很多人第一反应是用java.util.Stack或ArrayList。我觉得都不如Deque舒服。

Stack的问题在于，它继承了Vector，所有公开方法都带synchronized。我们需要的栈是线程私有的，当前线程独享，根本不存在并发写，锁完全是不必要的开销。而且Stack的类注释里早就被打上了问号，官方也推荐用Deque替代。

ArrayList当然能模拟：addLast对应入栈，removeLast对应出栈，peekLast看栈顶。但问题是语义不够直观，谁会愿意在代码里到处写removeLast？可读性差不说，还容易把add和addLast混在一起出错。Deque接口直接定义了push/pop/peek，它就是一个栈，语义一清二楚。

至于实现类选ArrayDeque还是LinkedList，我推荐ArrayDeque。它虽然是数组实现，看似在头部插入需要搬移元素，但实际上ArrayDeque的头部插入是在一个环形结构上处理的，head指针往前走，并不需要大范围搬移整个数组。头部增删是O(1)，只有容量用尽扩容时才发生一次性大搬移。相比之下，LinkedList每个元素都是一个节点对象，压栈动作频繁时，会在堆上产生大量小对象，GC压力更大。

顺手做个对比，方便你们记：

2.3 入栈出栈的细节：push、peek、pop 的顺序设计

使用Deque当调用栈，最核心的约定是：一个方法的enter必须与exit成对出现，且顺序要严格匹配方法嵌套。进入A方法时push一个span，A方法内部进入B方法时再push一个span，此时栈里是[A底, B顶]，栈顶正好就是当前正在执行的方法。退出B时pop掉B，退出A时再pop掉A。

入栈时不要把父子关系丢了。你在push当前span之前，应该先peek一下栈顶，拿到父span，给当前span设置parent。这样即便栈被清空了，span对象之间仍然可以通过parent指针恢复出整棵调用树。

出栈时有个小细节：pop出来之后先调用end()记录耗时，再判断栈是否为空。如果空了，说明这是最外层调用，这时线程的ThreadLocal要主动remove掉。这一步很多同学容易漏，漏掉它，线程复用时就会发生串号。

3. 实现细节：一段可以直接复用的 TraceContext

3.1 基础骨架：TraceContext 与 TraceSpan

直接上代码，这一段大家可以原样扒走改。我习惯把实现分成两个类：TraceSpan负责记录一段调用信息，TraceContext负责维护线程内的栈。

java复制public class TraceSpan {

    private final String name;
    private final long startTimeNanos;
    private long durationNanos;
    private TraceSpan parent;

    public TraceSpan(String name) {
        this.name = name;
        this.startTimeNanos = System.nanoTime();
    }

    public void end() {
        this.durationNanos = System.nanoTime() - startTimeNanos;
    }

    public String getName() {
        return name;
    }

    public long getDurationNanos() {
        return durationNanos;
    }

    public TraceSpan getParent() {
        return parent;
    }

    public void setParent(TraceSpan parent) {
        this.parent = parent;
    }
}

java复制public class TraceContext {

    private static final ThreadLocal<Deque<TraceSpan>> STACK = new ThreadLocal<>();

    public static void enter(TraceSpan span) {
        Deque<TraceSpan> stack = STACK.get();
        if (stack == null) {
            stack = new ArrayDeque<>();
            STACK.set(stack);
        }
        span.setParent(stack.peek());
        stack.push(span);
    }

    public static void exit() {
        Deque<TraceSpan> stack = STACK.get();
        if (stack == null || stack.isEmpty()) {
            return;
        }
        TraceSpan finished = stack.pop();
        finished.end();
        if (stack.isEmpty()) {
            STACK.remove();
        }
    }

    public static TraceSpan current() {
        Deque<TraceSpan> stack = STACK.get();
        return stack == null ? null : stack.peek();
    }

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

    public static String snapshot() {
        Deque<TraceSpan> stack = STACK.get();
        if (stack == null || stack.isEmpty()) {
            return "";
        }
        StringBuilder sb = new StringBuilder();
        Iterator<TraceSpan> it = stack.descendingIterator();
        while (it.hasNext()) {
            sb.append(it.next().getName());
            if (it.hasNext()) {
                sb.append(" -> ");
            }
        }
        return sb.toString();
    }
}

注意snapshot的遍历方向。ArrayDeque的iterator是从头部到尾部，也就是从最新方法到根方法。如果我想打印“根 -> 子 -> 当前”这种顺向链，就必须用descendingIterator从尾部往头部走。这个细节不写清楚，很多人第一次用就会发现打印出来的顺序是反的。

3.2 用 AOP 和 Filter 控制进入/离开的时机

光有上下文类还不够，关键是控制什么时候enter、什么时候exit。最省事的做法是在Spring里配一个AOP切面。

java复制@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Traced {
}

@Aspect
@Component
public class TraceAspect {

    @Around("@annotation(Traced) || @within(Traced)")
    public Object trace(ProceedingJoinPoint pjp) throws Throwable {
        String name = pjp.getSignature().toShortString();
        TraceContext.enter(new TraceSpan(name));
        try {
            return pjp.proceed();
        } finally {
            TraceContext.exit();
        }
    }
}

为什么要在finally里exit？因为方法可能抛异常，一旦异常中断，栈顶span就必须被弹掉，否则下一次进入同一个线程的方法调用时，栈里会残留脏数据。AOP的环绕通知天然给了你“方法入口”和“方法出口”两个时机，try-finally是标准写法。

Web入口层还需要一个Filter来创建根span和做最终清理，我习惯这样写：

java复制@Component
public class TraceFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        TraceContext.enter(new TraceSpan("http:entry"));
        try {
            chain.doFilter(request, response);
        } finally {
            TraceContext.clear();
        }
    }
}

这里有个细节值得提一下：入口span和AOP的span是嵌套关系吗？是的。Filter处理请求时，栈里先有“http:entry”，然后进入Controller方法时AOP再push一个“Controller.method”，接着往里一层层push。等整个请求结束，Filter的finally把整根线程上的ThreadLocal remove掉，这一条请求的上下文生命周期才算真正结束。

3.3 线程池复用场景下的清理防线

如果你只处理主线程上的同步调用，上面的代码已经够用了。但服务端不离线程池，尤其现在@Async、CompletableFuture满天飞。线程池里的线程是长期存活并复用的，如果任务本身没有进入/退出上下文，或者某个任务只enter不exit，那下一次任务从池子里捞到这个线程时，上一轮残留的栈还挂在ThreadLocal上。

我的防线很简单，给所有外部提交到线程池的任务包一层装饰器：

java复制public class TraceTaskDecorator implements TaskDecorator {

    @Override
    public Runnable decorate(Runnable runnable) {
        return new Runnable() {
            @Override
            public void run() {
                try {
                    runnable.run();
                } finally {
                    TraceContext.clear();
                }
            }
        };
    }
}

在Spring里，可以通过ThreadPoolTaskExecutor.setTaskDecorator()把它挂上去。这样任务一跑完，子线程里的ThreadLocal就被清干净，不管任务内部有没有正常退出，都不留尾巴。

但要注意：这个装饰器只清当前子线程的上下文，不负责把父线程的上下文带到子线程。如果业务上需要子任务感知父调用链，得自己把父线程的栈快照传进去，或者干脆用成熟的TTL组件。这个等下一节专门说。

4. 实战中会遇到的问题与排查技巧

4.1 getMap() 为 null 时意味着什么

很多同学读ThreadLocal源码时盯上了getMap(Thread)方法，想知道它到底返回啥。这个方法是包内可见的，业务代码无法直接调用，但你可以通过反射看当前线程的threadLocals字段：

java复制Field f = Thread.class.getDeclaredField("threadLocals");
f.setAccessible(true);
Object map = f.get(Thread.currentThread());
System.out.println(map);

如果map是null，说明当前线程还没往任何ThreadLocal里写过值，或者之前set过但都被remove掉了。这不是bug，是完全正常的初始状态。在线程池里，一个长期不被塞ThreadLocal值的线程，它的threadLocals字段经常是null。所以网上搜到“ThreadLocal getMap”的时候，不用怀疑自己写错了，只要记住map的初始化是懒加载的：第一次set或者get走到setInitialValue时，才会通过createMap把map建出来。

排查上下文串号问题时，我会反射看一下线程池里的线程map里面有啥，能直接看到是谁往里面塞了值。这比瞎猜快得多。

4.2 上下文串号：老线程里的残留数据

我线上真遇到过：同一个Tomcat线程，第一次请求留下的调用栈没清干净，第二次请求进来到AOP时，ThreadLocal.get()拿到的栈里还有上一次请求的span。日志一打印，栈里出现两个完全不相干的请求路径，排查了半天才意识到是串号。

这个问题有两个根因：

一是根span的清理时机不对。Filter的finally里如果只调用exit()，不调用clear()，那当栈里还有其它span没弹完时，整个过程不会真正清掉ThreadLocal。例如异步线程池里跑的任务没走完，或者某段逻辑代码在Filter之后才异常退出，栈就可能残留。

二是覆盖不完整。比如某些内部的ScheduledTask直接往线程池丢任务，没走Spring MVC的Filter，那Filter清理逻辑对它就是失效的。所以全链路上下文管理，必须有一条防守底线：任何进入线程池的任务，run方法里都要有finally + clear的兜底。

另外说个坑：只把Deque清空不算完，必须remove掉ThreadLocal本身。因为ThreadLocalMap的key是弱引用，value是强引用。如果线程里的map上还挂着value，即使Deque清空成了空对象，这个entry也会长期站在线程的threadLocals数组里。在池化线程上，这等于不定期泄漏。

4.3 异步边界：ThreadLocal 传不过去的解法

线程池子线程拿不到父线程的ThreadLocal，这是体系结构决定的，threadLocals就是Thread实例自己的字段。想让异步任务也感知调用链，大概有三种方案，我按推荐度排一下：

第一种，手动传递父span引用。提交任务的时候，把TraceContext.current()拿到的父TraceSpan作为参数传进任务里。任务开始执行时，先把它作为父节点enter一个带线程标记的子span，任务结束再exit。这个方案完全可控，代码量也不大，适合异步点不多的项目。

第二种，用TransmittableThreadLocal。阿里开源的那套，专门解决线程池场景的上下文传递问题。它通过装饰Runnable/Callable，在任务执行前capture父线程上下文，执行完再restore回来。如果你项目里用的Maven，引入依赖就行，配合TaskDecorator也很顺手。

第三种，用InheritableThreadLocal。它的机制是new Thread的时候，直接把父线程的map拷一份给子线程。缺点是线程池复用线程时，子线程并不会每次都重建，第一次继承的旧值可能一直串下去。所以在线程池场景下，我不建议单独依赖它。

不管选哪种，最终都要回到TraceContext这套模型上来。TTL传递的只是一个值对象，真正能表达“调用栈嵌套深度”的，还是我们在任务内部手动enter/exit的那套动作。

4.4 性能开销实测与采样降级

写这种框架代码，避不开性能问题。我简单实测过，ThreadLocal.get()加ArrayDeque.push这套操作，单次大概在几十纳秒级别。一个enter加一个exit，算上TraceSpan对象的创建，大概几百纳秒。注意，这里指的是纯数据结构开销，不是Spring AOP的反射和代理开销。

如果你在方法上挂了AOP，数据结构的成本就只占很小一部分了。一次带环绕通知的方法调用，即使切面里什么都不做，也要消耗几微秒，因为涉及代理对象、切面链、反射调用这些动作。对于单次请求上百个方法调用的业务，耗时会累积到几毫秒。低频接口可以忽略，高频小请求的接口就要留个心眼。

我用的降级手段有三个：

• 采样开关。用一个全局的AtomicBoolean控制是否开启调用栈，或者按requestId的哈希值决定命中百分比。命中率1%的时候，线上暴风式跑也没压力。
• 深度限制。检查Deque.size()，超过某个阈值比如50，就不再继续push新span，只累加一个计数器。防止异常递归或超深嵌套把内存撑爆。
• 懒创建span。平时只在栈里放极简id，只有到转储那一刻才去组装完整方法名和耗时信息，减少无谓的字符串和对象分配。

这三个手段一起上之后，我在一个日请求量千万级的老项目上跑过，开销基本可以忽略，但排查问题时又能随时打开全量开关复现现场。

在我实际使用中，这套“ThreadLocal + Deque”的上下文管理术已经帮我解决了不止一次线上问题。印象最深的是有一次报障说某个订单状态被改了两次，通过调用栈快照直接看到同一个线程里先后有两个方法改了状态，起因是代码里的一次并发重入，如果是以前靠requestId捞日志，这个根因不知道要捞多久。

现在我已经把这套逻辑封装进了一个项目私有starter，开关一开，所有Service方法自动进栈，开关一关，连AOP都直接跳过。如果你也在为嵌套调用不可见、异步上下文断链头疼，完全可以照这个思路做一个轻量版，它不复杂，但足够锋利。