← 课程目录 🚀 从零到一
📐 学习维度 阶段7 · 第28章 开源项目源码精读 🚀 从零到一 📚 课程目录 🏠 首页 🛤️ 学习路径

28.15.1 asyncTool 源码:WorkerWrapper 任务编排核心:依赖图、串并行组合、超时与回调

审校 2026-09-26 · 素材来源:zcode会话《Java项目分析与架构亮点解读》(项目源码分析)
📑 本篇章节导航 (共8节,点击直达)
场景:一个聚合接口的编排困境类比:装修队的工序图可跑示例:三行代码拼一个 DAG一次典型执行时序原理拆解:work() 是灵魂踩坑清单什么时候不该用它面试怎么问

购物车页要同时查用户、商品、库存、优惠券,库存还依赖商品 ID。手写 CompletableFuture 能跑,但每一步没有独立回调、超时要自己算、失败降级要一层层 handle。这篇拆京东开源的 asyncTool,看 WorkerWrapper 怎么把这件事做简单。

前置阅读:第 7 章讲过 CompletableFuture。这篇看 asyncTool 怎么把依赖图做成框架。

场景:一个聚合接口的编排困境

先看痛点。你要拼一个详情页,四路 RPC 并行,其中一路串行依赖另一路:

asyncTool 的答案:把每个耗时单元包成 WorkerWrapper,声明依赖关系,框架负责调度。它是 CompletableFuture 的增强替代品,核心逻辑只集中在 Async 和 WorkerWrapper 两个类。

类比:装修队的工序图

把任务编排想象成装修。水电、瓦工、木工是三个工种(WorkerWrapper 节点)。

整套图就是一个 DAG(Directed Acyclic Graph,有向无环图,任务按箭头方向执行、不能成环的数据结构)。

可跑示例:三行代码拼一个 DAG

先引入依赖(jitpack 仓库),然后实现两个接口:


public class QueryUserWorker implements IWorker<String, User>, ICallback<String, User> {
    @Override
    public User action(String userId, Map<String, WorkerWrapper> allWrappers) {
        return userServiceRpc.query(userId);   // 耗时逻辑
    }
    @Override
    public User defaultValue() { return new User(); }  // 超时/异常兜底
    @Override
    public void result(boolean success, String param, WorkResult<User> r) {
        // 每个单元独立回调,打日志、埋点都在这
    }
}

再用 Builder 声明依赖,B、C 都依赖 A,A 完成后自动并行:


WorkerWrapper<String, User> wA = new WorkerWrapper.Builder<String, User>()
        .worker(a).callback(a).param("0").id("A").build();
WorkerWrapper<String, Integer> wB = new WorkerWrapper.Builder<String, Integer>()
        .worker(b).callback(b).param("1").depend(wA).id("B").build();
WorkerWrapper<String, String> wC = new WorkerWrapper.Builder<String, String>()
        .worker(c).callback(c).param("2").depend(wA).id("C").build();

Async.beginWork(3000, wA);   // 阻塞,全组最多 3 秒
User aResult = wA.getWorkResult().getResult();   // 取结果

值得注意:Builder 的 build() 方法会自动帮你把对端的 next/depend 反向补全。你只管声明一边,另一边框架补上,避免漏配导致节点被孤立。

一次典型执行时序

拿 A→(B,C) 这个图走一遍:

如果 C 这一路 RPC 挂了 5 秒,全组不会陪着等:预算耗尽,C 被标记 TIMEOUT,调用方拿到 defaultValue() 的兜底值,页面照常渲染,只是少一块数据。

原理拆解:work() 是灵魂

整体结构只有两层:


Async(入口,静态门面)
  └─ beginWork(timeout, wrappers)   // 阻塞到全部完成或超时
       └─ WorkerWrapper<T,V>(DAG 节点)
            ├─ IWorker<T,V> worker      // 业务逻辑
            ├─ ICallback<T,V> callback  // 每个单元的回调
            ├─ nextWrappers    // 出边:我后面的节点
            ├─ dependWrappers  // 入边:我依赖的节点(DependWrapper)
            ├─ state: AtomicInteger  // INIT/FINISH/ERROR/WORKING
            └─ workResult: WorkResult<V>  // SUCCESS/TIMEOUT/EXCEPTION/DEFAULT

WorkerWrapper.work() 的执行流程(Async.java 的 beginWork 加 WorkerWrapper.java 的 work()):

1. beginWork 把起始 wrapper 用 CompletableFuture.runAsync 提交线程池;

2. 每个 wrapper 的 work() 里依次做:检查超时 → 检查是否已执行(CAS 去重)→ 检查跳过机制 → 无依赖直接 fire(),有依赖走 doDependsOneJob / doDependsJobs;

3. 自己跑完调 beginNext(),把下游 wrapper 再丢进线程池,残余超时时间透传给下游;

4. 顶层 allOf(futures).get(timeout) 兜底,超时就递归找出所有节点 stopNow() 标记失败,走默认值。

几个关键设计:

CAS 防重复执行。workerDoJob() 里有两道 CAS 闸口:进入前 INIT→WORKING,防并发重复触发;执行后 WORKING→FINISH,防超时返回默认值后、慢请求又回来二次覆盖结果。这是幂等(idempotent,同一操作执行多次效果不变)的精髓。

强依赖 / 弱依赖。DependWrapper.must 一个 boolean 实现 allOf / anyOf 语义:depend(a, true) 表示 a 必须完成我才跑;depend(b, false) 表示 b 完不完成无所谓。五个前置任务三个必须、两个可选,这种混合依赖 CompletableFuture 做不到,是 asyncTool 的杀手锏。

跳过机制。needCheckNextWrapperResult 处理边角场景:A、D 并行起步,D 先跑完直接把结果节点跑了,B、C 那条支链就短路不跑了,通过递归检查 next 链路状态实现。

线程复用。串行场景下,下游任务跑在完成得更慢的那个上游线程上,不开新线程。对比 thenCombine 链式调用更省线程。

残余超时时间透传。每个节点执行完,用 SystemClock.now() 算出本节点耗时,把 remainTime - costTime 传给下游。这保证整组总时长不超阈值,而不是每个节点各管各的超时——后者叠加起来可能等到 N 倍时间,聚合接口等不起。

失败降级内建。IWorker 接口自带 defaultValue(),任何节点超时或抛异常,WorkResult 就落到 DEFAULT 状态,下游照常拿兜底值继续跑。用 CompletableFuture 你得对每一步手写 exceptionally,节点一多就是灾难。

这也是它比 CF 适合做监控的原因:每个单元的 ICallback.result() 独立触发,成功失败、耗时参数全给你,接个埋点 SDK 就能画出整条链路的耗时瀑布图。

踩坑清单

什么时候不该用它

说完优点泼点冷水。它是侵入式接口,业务逻辑必须实现 IWorker,不像 CF 那样塞个 lambda 就完事;Async.executorService 若不显式传池则是全局 static,多组隔离时处处要小心。

所以判断标准很简单:中小型聚合接口、BFF 层多路编排、批查询并行化,用它很舒服;如果要做带人工节点、持久化、回滚补偿的大型工作流,去看 Liteflow 或状态机引擎,asyncTool 的轻是优点也是天花板。

面试怎么问

问1:asyncTool 和 CompletableFuture 比优势在哪?

答:每个节点有独立回调便于全链路监控、强弱混合依赖、全组超时加残余时间透传、每个节点自带失败默认值,这四点 CF 都要手写组合。

问2:WorkerWrapper 怎么防止任务被重复执行?

答:用 AtomicInteger 状态机加两道 CAS 闸口,进入前 INIT 转 WORKING 防并发触发,执行后 WORKING 转 FINISH 防超时后慢请求回来二次写结果。

问3:全组超时怎么实现的?

答:顶层 allOf().get(timeout) 兜底,超时递归对所有节点 stopNow() 标记失败;正常路径下每个节点扣掉已耗时间,把剩余时间透传给下游,保证总时长不超阈值。