企业官网建设流程全解析

前阵子排查一个接口变慢的问题，网关侧显示/api/order/list的平均耗时从 200ms 一路涨到 800ms。干活的第一件事是翻日志，结果日志里倒是不缺东西：Controller 打了耗时，Service 打了耗时，DAO 也打了耗时，可它们全是平铺的独立行，根本看不出谁调了谁。那一刻我意识到，单纯把埋点加得再密，也回答不了两个问题：这个请求到底走了哪几条路径？耗时到底堆积在哪个嵌套层级里？后来我给自己搭了一根“线程专属的调用栈”，用 ThreadLocal 绑定线程，用 Deque 保存调用层级，每个方法进入时压栈、返回时弹栈，请求结束把整条栈拿出来拼树，问题一下子就清楚了。Spring Insight 当年做请求跟踪时，走的也是这个上下文管理思路。

1. 一个慢接口引发的排查困境：调用层次去哪了

1.1 平铺日志解决不了“嵌套调用”问题

Java 服务端一个典型请求的处理路径大体是：Controller 收到请求，调 Service，Service 内先查缓存、再查数据库，可能还调了好几个内部方法。放到日志里，每一层都可以打一行耗时记录，但这里的核心问题是：这一行行记录之间没有父子关系。比如日志里同时出现OrderService.queryOrder cost=560ms和OrderMapper.selectById cost=480ms，你能推测前者包含后者，但不敢确定，因为你可能还有另一个StockService.checkStock也走了同一个 Mapper。没有调用关系，就无法判断这 560ms 是消耗在前面的缓存上、中间的主流程上，还是后面的库存校验上。

更麻烦的是，这种日志打多了以后，定位问题已经不是“看日志”，而是“猜日志”。一次线上故障，往往要同时对着十几个方法的耗时打点做排列组合，才能拼出一条可能的调用路径。而调用路径如果拼错了，接下来做的任何优化都可能打在错误的地方。所以做一个能真正还原调用顺序和嵌套层级的基础设施，比加更多打点更有价值。

1.2 每个请求其实都跑在一根专属线程上

Spring Web 容器在绝大多数情况下，会用请求线程串行处理一个请求，请求线程从上到下完成 Controller、Service、DAO 的调用，结束后返回响应。这个“线程”是天然的上下文容器——同一个请求里发生的一切都发生在同一根线程上，不同请求之间则天然隔离在不同的线程上。所以我们只需要把“当前请求的调用路径”挂在这根线程上，且保证进栈、出栈和清理时机正确，那么每个请求都会拥有一份只属于自己的调用记录。

这里有一个隐含前提：我们讨论的是同步请求处理模型。如果代码里大量使用异步、响应式、线程池，那上下文就不能只靠单根线程保存了，这部分我在后面专门讲。先把这个最经典的同步模型吃透，后面的异步改造才有基础。

1.3 ThreadLocal + Deque 组合的第一直觉

把 Deque 放进 ThreadLocal，等于每个线程都持有一个自己能读写的“栈”。进入一个方法时调用一次 enter 方法，把当前操作压到栈顶；方法返回时调用一次 exit，把栈顶弹出并记录结束时间；调用子方法时，再压入一层。这个模型跟 JVM 的调用栈非常像，只是多加了一层业务语义。Spring Insight 对请求的处理树展示，本质上也是先维护好这套线程内调用栈，再在请求结束时把栈拼成树。

2. 存储结构选型：ThreadLocal 隔离线程，Deque 复刻调用层级

2.1 ThreadLocal 只保证“每线程一份”，不保证“嵌套关系”

ThreadLocal 的实现是每个 Thread 内部有一个 ThreadLocalMap，键是 ThreadLocal 实例，值是你放进去的对象。它能保证不同线程的同一变量彼此不可见，解决并发污染的问题。但如果你只往里存一个字符串，例如“当前正在执行的方法名”，那么当你在一个方法里连续调用另外两个子方法时，旧方法名会被新方法名覆盖，嵌套关系就丢了。因此 ThreadLocal 里存的不应该是一个单值，而是一个完整的容器，这个容器要支持后进先出。

我见过不少初学者在这里犯迷糊：认为用 ThreadLocal 存个 List，在里边 append 方法名，就已经是调用栈了。实际上 List 只能表达“顺序”，不能表达“嵌套深度”。要表达嵌套，栈是最直接的数据结构——当前正在执行的方法永远是栈顶元素，它的上一层调用就是栈里下一个元素。这样无论是计算深度、找父级，还是出栈时计算耗时，都很自然。

2.2 为什么栈容器用 ArrayDeque 而不是 Stack 或 ArrayList

Java 里做栈有三类选择，对比一下就很清楚。

因为栈本身是线程私有的，不存在跨线程并发访问，所以不需要线程安全容器，反而要避免像 Stack 那样自带锁；ArrayDeque 作为双端队列，在头部做 push/pop 都是 O(1)，与调用栈的语义完全匹配。这里有个细节：不要在多个线程之间共享同一个 Deque，否则并发问题会重新出现。

还有一个更隐晦的原因：ArrayDeque 的迭代顺序是从头到尾，也就是说迭代时先看到最新的栈顶元素，这非常方便我们做“当前活跃调用链”的快照输出。如果用 ArrayList 模拟栈，拿到的列表顺序是反的，打印和排查都得再做一次 reverse，完全没有必要。

2.3 让每个栈元素变成一条完整的调用记录：Span

栈里光是存一个方法名还不够，我们要在出栈时还原耗时、父子关系、层级深度、开始顺序等信息，所以栈里的每一个元素最好是一个对象。我习惯把它叫 Span，这也是很多链路追踪系统里的通用叫法。Span 至少要包含 spanId、parentSpanId、operationName、开始时间、结束时间、耗时。入栈时生成 spanId 和上级 parentSpanId，出栈时记录结束时间并计算出耗时。由于 Deque 保留着父亲节点位置，parentSpanId 可以直接从栈顶下一个元素取得，整个调用链的树结构信息此时就已经完整了。

3. 核心实现：一版能直接抄走的上下文管理器

3.1 Span 模型：最小字段，够用就行

下面是一个最简版的 Span，字段直接暴露，方便理解，生产代码自行封装。

public class Span { public String spanId; public String parentSpanId; public String operation; public int depth; public long startTimeNanos; public long endTimeNanos; public long costNanos; public Span(String spanId, String parentSpanId, String operation, int depth, long startTimeNanos) { this.spanId = spanId; this.parentSpanId = parentSpanId; this.operation = operation; this.depth = depth; this.startTimeNanos = startTimeNanos; } public void finish() { this.endTimeNanos = System.nanoTime(); this.costNanos = endTimeNanos - startTimeNanos; } }

注意这里计时用的是System.nanoTime()，而不是System.currentTimeMillis()。nanoTime 不受系统时钟跳变影响，只适合计算时间差，不适合展示成具体时间点；展示用时间点可以另外记一个wallClockTime。

3.2 入栈、出栈与清理：三段式生命周期

核心管理器代码如下：

public class TraceContext { private static final ThreadLocal<Deque<Span>> STACK = new ThreadLocal<>(); private static final ThreadLocal<String> TRACE_ID = new ThreadLocal<>(); public static String traceId() { return TRACE_ID.get(); } public static Span enter(String operation) { Deque<Span> stack = STACK.get(); if (stack == null) { stack = new ArrayDeque<>(); STACK.set(stack); TRACE_ID.set(UUID.randomUUID().toString().replace("-", "")); } Span parent = stack.peek(); Span span = new Span( UUID.randomUUID().toString().replace("-", ""), parent == null ? null : parent.spanId, operation, stack.size(), System.nanoTime()); stack.push(span); return span; } public static void exit() { Deque<Span> stack = STACK.get(); if (stack == null || stack.isEmpty()) { return; } Span finished = stack.pop(); finished.finish(); Collector.offer(TRACE_ID.get(), finished); if (stack.isEmpty()) { STACK.remove(); TRACE_ID.remove(); } } public static void clear() { STACK.remove(); TRACE_ID.remove(); } }

关键点有两个：第一，第一次 enter 时才初始化 ThreadLocal，并把 traceId 一起挂到线程上，保证同一个请求内的所有 Span 共享同一个 traceId；第二，栈弹出后如果发现已经空了，说明这是最外层调用，这时必须调用remove()，而不是仅仅set(null)，否则 ThreadLocalMap 里的 Entry 会一直持有 value，线程池线程长期存活时可能造成内存滞留。

Collector 是一个采集队列，可以用ConcurrentLinkedQueue兜住所有已经完成的 Span，之后统一分析。示例里 exit 后在队列里扔了一个 span 对象；如果不想创建额外对象，可以只在出栈这一刻做一次聚合记录，但为了演示，入队是最直观的。

3.3 用 AutoCloseable 把清理锁死在 finally 语义里

手写 enter 和 exit 很容易在异常路径上出问题：方法里抛了异常，exit 不执行，栈就残留了脏数据。所以更稳妥的用法是做一个 AutoCloseable 的 Scope：

public class TraceScope implements AutoCloseable { private final Span span; private final boolean root; TraceScope(Span span, boolean root) { this.span = span; this.root = root; } @Override public void close() { TraceContext.exit(); } }

然后调用方这样写：

try (TraceScope scope = TraceContext.enter("OrderService.queryOrder")) { orderMapper.selectById(id); }

try-with-resources 会在代码块结束或抛出异常时自动调用 close，相当于把“出栈”和“异常兜底”都交给 JVM 处理。这一步极其重要，我见过很多 ThreadLocal 相关线上事故，最后根因都不是入栈逻辑，而是某个异常分支绕过了 exit。

3.4 把零散 Span 拼成一棵调用树

每个 Span 结束被塞进队列，请求结束时我们可以一次性把它们取回来，按照 parentSpanId 关联成树。

例如日志最终输出长这样：

traceId: e3b0c44298fc1c149afbf4c8996fb924 GET /api/order/list total=780ms ├── OrderService.queryOrder cost=560ms │ ├── CacheClient.get cost=30ms │ └── OrderMapper.selectById cost=480ms └── StockService.checkStock cost=210ms

看到这个树之后，我们一下子就知道瓶颈在OrderMapper.selectById这条 SQL 上。组装树的逻辑并不复杂，先按 spanId 建索引，再遍历所有 Span 把每个节点挂到 parentSpanId 对应的父节点下，最后 root 就是没有 parentSpanId 的那个节点。有了树，后续做耗时排序、P95 聚合、慢路径告警都比较自然。

4. 线程池是最容易击穿上下文边界的地方：一次串扰的完整排查

4.1 异步任务里的 traceId 丢失：为什么是必然的

把任务提交到线程池后，任务会在线程池的某个线程上执行，这个线程的 ThreadLocal 里什么都没有。即使之前线程池线程执行过同一业务代码，ThreadLocal 里存的也是上一次任务的上下文，与当前请求无关。所以只要你在异步任务里访问TRACE_ID.get()，得到 null 或者上一个任务的 traceId，根本不是 bug，这是线程模型决定的必然现象。

我记得第一次把调用栈接入一个含线程池的服务时，代码刚上线，日志里就出现了一批 traceId 为空的行。当时第一反应是“ThreadLocal 失效了”，后来把任务执行前后的线程名打印出来才意识到，线程本来就被切走了，ThreadLocal 再强也管不到别的线程。

4.2 主动传递上下文：提交任务前抓快照，执行任务前续接

解决办法是在提交任务时，把当前线程里的 traceId 和当前栈顶的 spanId 取出来，随任务传过去；任务开始执行前，在目标线程上续接一个上下文；任务跑完后无条件清理。一个包装 Runnable 的小工具就能做到：

public class TraceRunnable implements Runnable { private final Runnable delegate; private final String traceId; private final String parentSpanId; public TraceRunnable(Runnable delegate) { this.delegate = delegate; this.traceId = TraceContext.traceId(); Span top = TraceContext.top(); this.parentSpanId = top == null ? null : top.spanId; } @Override public void run() { TraceContext.continueWith(traceId, parentSpanId); try { delegate.run(); } finally { TraceContext.clear(); } } }

其中top()返回栈顶 Span，没有则返回 null；continueWith(traceId, parentSpanId)的作用是绕开自动生成 traceId 的逻辑，沿用父线程的 traceId，并预先压入一个表示“异步子任务”的父 Span，让后续 enter 的 Span 都挂在它下面。提交线程池时只要把原始 Runnable 包一层 TraceRunnable，上下文就不会断。这里注意，续接时不要依赖 InheritableThreadLocal，原因我稍后专门说。

4.3 线程复用导致的数据串扰：从现象到根因

在线程池场景下，真正隐蔽的坑是数据串扰。曾经出现过这样一个现象：新任务 B 的日志里 traceId 是任务 A 的，而且 B 的第一个 Span 的 parentSpanId 指向了一个早就结束的 Span，整条链路完全错位。我们当时的排查步骤大致如下：

1. 先对比日志时间戳和线程名，确认 A 和 B 恰好跑在同一根线程上；
2. 在 B 的入口打点，打印线程内 ThreadLocal 的 Deque 内容，发现非空，里面还有 A 的 Span；
3. 检查 A 的清理逻辑，发现 A 的业务代码里有一个提前 return 的异常分支，这个分支没有执行 exit；
4. 由于线程池线程不会因为任务结束而销毁，残留的 Deque 就被下一个任务 B 捡到了。

修复方式就是前面说的：要么用 AutoCloseable 兜底，要么在任务收尾处强制调用TraceContext.clear()，而不依赖业务代码自己去弹栈。线程池复用是 ThreadLocal 生命周期管理里最需要谨慎的场景，因为它会放大“忘记清理”的后果。

4.4 InheritableThreadLocal 为什么救不了线程池

有人会问：那用 InheritableThreadLocal 是不是就行了？它确实能在创建线程时把父线程的值复制给子线程，但线程池里的线程不是每次执行任务都新建的，它是在池子建立时创建的，只复制一次之后再不更新。所以任务 B 执行时，它拿到的很可能是线程池启动那一刻父线程的旧快照，甚至什么也没拿到。就算你每次提交任务前手动 set 一份快照，InheritableThreadLocal 也不会在任务执行前自动帮你“续接当前调用栈”，它解决的只是“线程创建时的继承”，而不是“任务执行时的传播”。我们在实践中要记住：线程池场景必须靠显式传递上下文，比如上面这种 Runnable 包装，或者使用专门做线程间上下文传递的增强工具类。

5. 把这段代码推向生产：性能、开关和分布式扩展

5.1 一次入栈出栈的量级，和最容易忽略的开销来源

简单算一笔账：一次 enter 要做一次 ThreadLocal 读取、一次 peek、一次对象创建、一次 UUID 生成；一次 exit 要做 pop、一个时间戳和一次队列 offer。在 JVM 跑热之后，这样一组操作大概在几百纳秒到 1 微秒之间。对绝大多数业务方法来说，这个开销可以忽略。但如果一个请求内部有几十万个埋点，比如在极高频循环里埋点，那就不一样了。这里最容易忽略的开销往往不是栈操作本身，而是 UUID 的生成和对象分配。生产环境可以改用进程内自增序列或雪花算法生成 spanId，也可以把 Span 对象池化复用。至于时间，用System.nanoTime()就对了。

还有一点要注意：采集队列如果只进不出，长时间运行会积压大量 Span 对象。所以生产级设计里要有定时刷新，请求结束后把该请求的 Span 组装成树，然后释放。

5.2 埋点必须加上总开关和采样策略

给上下文管理器加一个总开关，是把它放到生产环境的第一步。最简单的做法是在 enter 方法开头判断一个静态 boolean，关闭时直接返回一个 no-op Scope，这样所有埋点代码仍然在，但实际开销几乎为零。进一步可以做采样：按 traceId 的 hash 对某个采样率取模，比如只采样 10% 的请求，或者按接口路径清单开启。这个思路和很多链路追踪组件里的动态采样如出一辙。

public static TraceScope enter(String operation) { if (!TraceConfig.enabled()) { return NoopScope.INSTANCE; } // 原逻辑 }

采样时要额外注意：如果只记录部分请求，那么 traceId 最好每个请求都生成，否则日志里另一半请求没有 traceId，后续想按请求关联日志就做不到了。也就是说，开关可以关掉 Span 细节，但 traceId 这层最好保持全量。

5.3 从线程栈到跨服务调用链的演进路径

单机的线程专属调用栈解决的是“一个请求在同一个线程内的嵌套调用”。一旦调用跨越了服务，比如订单服务调用支付服务，线程栈就断在进程边界上。演进思路其实是透明的：把 traceId 和当前 spanId 塞进 RPC 或 HTTP 的 header，被调服务在入口处接住，继续用同样的方式压栈、出栈，返回时再把新的 spanId 传回调用方。这样一来，多个服务的线程栈通过同一个 traceId 串成一条跨进程的调用链。了解了这套模型，再看各类开源链路追踪系统里 trace、span、parentSpanId 这些词汇，就会觉得非常眼熟，因为你已经亲手实现过一版最小闭环。

最后再说一点个人经验。写这种线程上下文管理代码，最重要的不是入栈逻辑有多精巧，而是出口意识：入口处创建的资源，出口处一定要清干净，不管是正常返回还是异常退出。把清理当成锁的释放来看待，线上基本不会出幺蛾子。我第一次实现这套东西时，就是在线程池场景栽了跟头，补了一个“任务级 finally 清理”之后才彻底稳定，后来每次接新需求，我都先问一句：这段代码的边界在哪里，结束路径有几条。