SuperAPI AI 工具集

kp-callback-bridging

编程与开发

查看项目

更新于 10-16 16:27

技能介绍

用途

kp-callback-bridging 用于把基于回调(callback)的 API 包装成 Kotlin 的挂起函数(suspend fun),使调用方能够以符合协程习惯的方式使用这些接口。其核心是 suspendCancellableCoroutine { … },在包装的同时保证协程被取消时能够注销回调。

主要能力

suspendCancellableCoroutine<T> { cont -> … } 是一个协程构建器,它会:

  • 挂起调用方协程;
  • 提供一个 CancellableContinuation<T>(即 cont);
  • 在调用 cont.resume(value) 或 cont.resumeWithException(e) 时恢复调用方;
  • 如果父协程被取消,则执行通过 invokeOnCancellation { … } 注册的代码块,从而干净地注销回调。

示例:

suspend fun fetchUser(id: UserId): User = suspendCancellableCoroutine { cont ->
    val request = api.fetchUser(id, object : Callback<User> {
        override fun onSuccess(user: User) { cont.resume(user) }
        override fun onError(e: Throwable)  { cont.resumeWithException(e) }
    })
    cont.invokeOnCancellation { request.cancel() }
}

其中 invokeOnCancellation 钩子是关键:没有它,取消调用方协程会导致回调泄漏,第三方 API 会一直持有引用直到回调触发(也可能永远不触发)。

应优先使用 suspendCancellableCoroutine 而非 suspendCoroutine。两者都存在,但不可取消的变体没有 invokeOnCancellation 钩子,不应被用于任何持有外部资源的场景。

对于事件式(多次触发)的回调,应使用 callbackFlow:

fun sensorReadings(): Flow<Reading> = callbackFlow {
    val listener = object : SensorListener {
        override fun onReading(r: Reading) { trySend(r) }
    }
    sensor.register(listener)
    awaitClose { sensor.unregister(listener) }
}

callbackFlow 返回一个 Flow<T>,其发射来自回调。awaitClose 代码块在流被取消时执行,注销逻辑就放在这里。

注意:CancellableContinuation 只能被恢复一次,否则会抛出 IllegalStateException。如果回调可能多次触发,说明它是事件流,应使用 callbackFlow 而非 suspendCancellableCoroutine。

使用方式与决策要点

  • 一次性回调(成功或失败,只触发一次)→ 使用 suspendCancellableCoroutine。
  • 多次触发回调(事件随时间到达)→ 使用 callbackFlow。
  • 始终注册取消处理器(invokeOnCancellation / awaitClose)来注销回调。
  • 测试包装器时,取消调用方协程并断言底层回调已被注销。

适用场景

  • 包装使用回调/监听器的第三方库(Java SDK、网络客户端、硬件 API)。
  • 将 Android API(OnClickListener、LocationListener、传感器回调)桥接为协程 API。
  • 将一次性 future 风格 API(CompletableFuture、ListenableFuture)转换为 suspend fun。
  • 将轮询/事件循环转换为 Flow(每次发射来自一个回调)。

不适用场景

  • API 已经返回 Deferred、CompletableFuture 或协程——应使用 .await() 或已有的桥接函数。
  • 回调多次触发且需要响应每一次调用——这不是一次性 suspend fun,而是 Flow,应使用 callbackFlow { … }。

限制与反模式

  • 忘记 invokeOnCancellation:调用方取消时回调会无限期残留,造成内存泄漏。
  • 对持有外部资源的场景使用 suspendCoroutine(不可取消变体):没有机会清理。
  • 多次恢复 continuation:会抛出异常并使协程崩溃。
  • 用 suspendCancellableCoroutine(一次性)包装事件流:会静默丢弃第一次之后的所有发射。
  • 调用在其它线程上执行回调的第三方代码时,未考虑接收协程上下文是否在意(多数不在意,但 UI 线程在意)。

相关技能

  • kp-coroutine-scope——拥有被包装调用生命周期的作用域。
  • kp-flow-cold-vs-hot——callbackFlow 产生的是冷流。
  • kp-anti-patterns——注册回调却不配对注销是典型的 Kotlin 坏味道。

参考资料

  • Kotlin Coroutines(Marcin Moskała)——关于 suspendCancellableCoroutine 与桥接的章节。
  • Kotlin 协程官方指南——协程取消;callbackFlow 文档。