协程里的“信号灯”:CompletableDeferred,一个被低估的 Kotlin 并发神器

18 阅读4分钟

回调地狱、初始化时序、跨线程等待——一个类全搞定。

一、从一个真实的痛点说起

做车载 Android 开发,有个经典难题: 车机服务是异步连接的,但业务代码是同步写的 。

比如获取 VIN 码(车架号): Device 对象创建后, vin 字段可能还是空的——要等系统服务真正 onConnected() 回调回来才有值。可下游几十个模块都依赖 VIN,难道让它们都去注册回调?

真实解法:

object AppDelegate : AppManager { // 信号灯:车服连接完成的"一次性门禁" private val initAwaitDeferred = CompletableDeferred() suspend fun awaitInitialization() = initAwaitDeferred.await() private fun initDevice() { // ... if (inner_vin == "" || inner_vehicle_type == "") { connectable.registerConnectWatcher(object : IConnectable.IConnectWatcher { override fun onConnected() { // ... 缓存 vin/vehicleType initAwaitDeferred.complete(Unit) // 绿灯! } }) connectable.connect() } else { initAwaitDeferred.complete(Unit) // 已经有值,直接放行 } } }

下游任何协程只需要一行:

AppDelegate.awaitInitialization() // 挂起等待,不阻塞线程 

doSomethingWithVin()

回调只注册一次,等待方可以有一万个 ——这就是 CompletableDeferred 的精髓。

二、CompletableDeferred 是什么

一句话: 一个可以由你手动“完成”的协程结果容器 。 它的 API 极简,核心就四个方法:

和兄弟们的区别一图看懂:

Deferred → 结果由 async 块自己算出来,你只能等 CompletableDeferred → 结果由"别人"在任意时刻、任意线程塞进来 Channel → 一对多的数据流,多次传递 CompletableDeferred → 一次性的"结果信号",完成即封盘

注意一个细节: complete 只能成功一次 ,第二次调用返回 false 。它天生就是幂等的“一次性开关”。

三、进阶用法:把回调改造成带超时的挂起函数

上面的例子是“等一个事件”。更常见的场景是 老代码里满天飞的回调接口 ,怎么包装成优雅的 suspend fun ? 还是真实生产代码——车控 SOA 服务的请求封装:

private suspend fun request( id: String, timeMillis: Long = TIMEOUT_TIME, block: suspend () -> Response?, ): SoaRep { val deferred = CompletableDeferred<Response?>() // 后台协程执行真正的车控调用,结果塞进 deferred soaScope.launch { try { deferred.complete(block()) } catch (e: CancellationException) { deferred.complete(null) } catch (e: Exception) { deferred.completeExceptionally(e) } } return try { withTimeout(timeMillis) { deferred.await() // 挂起等待,带超时保护 }.mapToSoaRep() } catch (e: TimeoutCancellationException) { /* 超时兜底 */ } }

这段代码浓缩了三个实战要点: 

 1. 回调 → 挂起 : deferred.await() 把异步结果“同步化”,调用方可以直接 val rep = request("lock_door") ,不再嵌套回调。 

2. 超时是标配 :车控指令绝不能无限等。 withTimeout 包住 await() ,超时异常单独捕获。裸写 await() 不加超时,是线上 ANR 和僵尸协程的重灾区。 

3. 异常要分拣 : CancellationException 不能当普通异常吞掉(否则破坏结构化并发),要单独 complete(null) 处理。

四、什么时候用,什么时候别用

适合的场景:

- ✅ 初始化门禁:等 SDK / 车服 / 数据库连接就绪(本文案例一)

- ✅ 回调改造:把第三方回调 API 桥接成 suspend 函数(案例二)

- ✅ 测试同步屏障:单测里用 CompletableDeferred() 卡住协程,验证中间状态

- ✅ 一次性握手:跨模块 / 跨进程的结果回传

不适合的场景:

- ❌ 多次事件推送 → 用 SharedFlow / Channel

- ❌ 单协程内异步计算 → 用 async 就够了

- ❌ 需要重试、重新完成的场景 → 它完成即封盘,不能 reset

五、三个容易踩的坑

坑 1:忘记超时 await() 永远挂起 = 线程不挂但协程僵尸。所有 await() 都问自己一句:“它不来怎么办?” 

 坑 2:在 complete 的瞬间还有竞态 多个线程同时抢 complete() ,只有第一个生效。如果你的逻辑依赖“谁完成它”,需要额外加状态判断,而不是依赖 complete 的返回值。

 坑 3:异常传递会“炸”所有等待者 completeExceptionally 后, 每一个 正在 await() 的协程都会抛异常。多人等待的场景要确认等待方都有 try-catch。

六、总结

CompletableDeferred 本质上是协程世界的 手动挡 Deferred : - 它是 信号灯 ——把“某件事完成了”这件事,从回调世界翻译成挂起世界; - 它是 桥 ——横跨回调 API 与协程 API 的单行本桥梁; - 它是 门禁 ——一次 complete,放行所有等待者。 下次当你又要注册一个全局回调、又要在某处写一个 @Volatile var isReady = false 加死循环轮询时——停一下,试试 CompletableDeferred 。