做React Native原生模块开发的人应该都经历过这种时刻Java侧拿到的数据是异步的回调一层套一层还没等逻辑理清楚JS侧又在等着Promise.resolve。那段时间我一直在找能把这堆异步流程“掰直”的工具尝试过手写回调、RxJava、Kotlin协程最后在Android端稳定用下来的反而是Bolts。这个名字听起来很“硬核”的小库其实解决的就是任务编排和异步链式调用的问题体积小、无额外依赖、API直观特别适合嵌在RN原生模块这种每次调用都要跨桥接的敏感场景里。这篇文章就围绕“React Native Android Bolts”这个组合把我在实际项目里怎么用、为什么用它、踩过哪些坑尽量完整地整理出来。适合正在做RN原生模块封装、被回调地狱折磨或者想给JS侧提供一个稳定异步接口的人参考。如果你只是想在Android原生里找一个轻量Promise工具Bolts也一样值得看。1. 为什么React Native的Android端需要Bolts1.1 原生模块异步回调的痛点RN的JS侧天生是单线程事件循环Promise和async/await用得很顺手。但Android原生侧不一样很多系统能力都是异步的读取设备信息要走异步查询、申请权限要在回调里拿结果、下载文件要监听进度、数据库操作要在IO线程执行。把这些异步逻辑暴露给RN时最常见的做法是在ReactMethod里接收一个Callback参数然后在异步回调里触发它。单个回调还行一旦有两个以上的串行依赖代码就变成嵌套地狱。比如要先检查权限、再获取定位、再读取传感器数据最后才返回给JS侧那个缩进基本就是“圣诞树”。更麻烦的是RN Bridge对方法调用有超时和异常处理的隐性要求原生侧一旦报错没回调JS侧就会一直挂着表现为界面卡死、加载白屏。1.2 为什么是Bolts而不是手写回调Bolts最早是Parse团队开源的工具库Android端主要包含bolts-tasks和bolts-applinks两个模块我们日常用到的就是bolts-tasks。它提供了一个类似Promise的Task类支持链式调用、组合并发、超时控制、错误传播整个库加依赖才几十KB不用引入RxJava那种庞然大物。在RN原生模块场景里手写回调的问题不仅仅是缩进难看更难处理的是“异常分支”和“线程切换”。比如定位获取失败后要重试一次再失败最终统一回调给JS。手写Callback很难优雅表达“失败重试”和“结果合并”而Bolts的continueWithTask天然支持在延续里返回一个新Task相当于递归、重试、分支都变成了普通代码。1.3 横向对比RxJava、协程、Bolts怎么选有段时间我在RN模块里试过RxJava确实强大但对RN场景来说有几个问题第一依赖太重一个网络请求模块引入RxJava会让apk体积明显增加第二线程模型过于灵活用不熟的话反而会在错误线程回调JS问题非常难查第三学习曲线陡团队里不是每个人都熟悉Rx操作符。Kotlin协程是另一个方向如果你是纯Kotlin项目lifecycleScope或者自定义CoroutineScope确实舒服。但RN原生模块要对接JS侧的Promise协程的suspend函数和RN Bridge的Callback/Promise交互还是需要自己搭桥而且老项目里Java代码居多时协程的接入成本并不低。Bolts在这三者里属于“刚刚好”的那个它不要求你掌握响应式编程也不依赖Kotlin协程运行时就是一个纯粹的Java库。你可以在任意Java/Kotlin方法里创建Task链式组合最后在回调里resolve给RN。这种“低心智负担”的特性对长期维护的RN原生模块来说非常友好。2. Bolts核心类与链式任务解析2.1 Task、TaskCompletionSource、ExecutorBolts的TaskTResult是核心表示一个异步操作的结果泛型TResult就是最终产出的数据。创建Task的几种常见方式// 直接返回一个已完成的结果 TaskString ready Task.forResult(ok); // 在后台线程执行一段代码返回Task TaskBitmap loadTask Task.callInBackground(new CallableBitmap() { Override public Bitmap call() { return loadBitmapFromFile(path); } }); // 手动控制完成时机相当于Promise的resolve/reject TaskCompletionSourceString tcs new TaskCompletionSource(); // 在任意异步回调里 tcs.setResult(权限已授予); // 或者 tcs.setError(new RuntimeException(用户拒绝));TaskCompletionSource特别适合把“回调式的系统API”包装成Task。比如申请危险权限系统通过onRequestPermissionsResult回调结果你可以在发起申请前创建一个tcs在回调里setResult或setError外部就拿这个tcs.getTask()作为Task使用。这样RN模块内部就不用在回调里再套Callback了。Executor是Bolts里容易被忽略但极其重要的参数。Task.call、continueWith这类方法都可以传Executor用来指定“在哪条线程上执行延续”。默认情况下如果没有传Executor延续会在“调用continueWith的那条线程”上执行这一点后面会重点讲它既是Bolts好用的原因也是大家踩坑的重灾区。2.2 链式组合与并发编排whenAll与whenAnyRN原生模块经常要并行获取多个数据再合并成一个结果。比如一个“设备信息聚合器”需要同时读取电池状态、网络类型、系统版本。三个数据源的耗时都不可控串行会拉长总耗时并行才是正确姿势。Bolts提供了Task.whenAll(Collection? extends Task?)在所有Task都成功后返回一个新的Task结果是一个List 还有一个Task.whenAnyResult只要其中一个成功就返回。RN场景下我几乎天天用whenAll配合continueWith合并结果TaskBatteryInfo batteryTask getBatteryTask(); TaskNetworkInfo networkTask getNetworkTask(); TaskBuildInfo buildTask getBuildTask(); TaskListObject combinedTask Task.whenAll( Arrays.asList(batteryTask, networkTask, buildTask) ).continueWith(new ContinuationListObject, DeviceInfo() { Override public DeviceInfo then(TaskListObject task) throws Exception { if (task.isFaulted()) { throw task.getError(); } ListObject resultList task.getResult(); return new DeviceInfo( (BatteryInfo) resultList.get(0), (NetworkInfo) resultList.get(1), (BuildInfo) resultList.get(2) ); } });这里注意whenAll有一个行为只要有一个Task失败整个组合Task就会立刻进入faulted状态其他Task虽然在跑但结果不会再被收集。所以如果需要“单点失败不拖垮整体”的容错逻辑最好在每个子Task里先做一次异常兜底比如在延续里捕获异常并返回默认值。2.3 超时、取消与错误传播机制RN侧最怕的就是原生方法“没响应”。JS的Promise如果一直pending界面上经常就表现为白屏或一直转菊花。Bolts的withTimeout可以给Task加超时保护TaskString initTask doHeavyInit() .withTimeout(3000, Executors.newSingleThreadExecutor());超时后Task会变成faulted状态抛出的异常是java.util.concurrent.TimeoutException。在RN模块里这个异常可以转换成JS侧的Error让JS代码进入catch分支避免界面挂死。Bolts的取消是“协作式”的通过CancellationToken实现类似“调用了cancel()后任务内部需要主动检查token.isCancellationRequested()并停止工作”。RN原生模块里我用得不多因为大部分系统API本身就是不可中断的但如果你自己写的是一个循环轮询任务配合token可以让用户离开页面时尽快释放资源。错误传播机制上Bolts会在链式调用中自动传递异常并且continueWith和onSuccess的语义有区别onSuccess只有在前一个Task成功时才会执行失败直接跳过并把异常往下抛continueWith则无论成功失败都会执行。需要针对“失败分支”做清理工作时continueWith就比onSuccess灵活。3. 实操在RN原生模块中用Bolts封装异步能力3.1 环境与依赖配置我平时用的是经典RN Bridge非TurboModule架构Gradle配置里加一行依赖就搞定dependencies { implementation com.parse.bolts:bolts-tasks:1.4.0 }Bolts库的groupId是com.parse.bolts接在RN项目里不需要额外配置仓库Maven Central和JCenter镜像都有。如果你做的是Kotlin模块Java的Callable、Continuation接口直接可以用无非是多写几个SAM转换。需要提醒的是RN社区有些老文档会把Bolts和Parse SDK混在一起说实际上bolts-tasks是独立模块不需要引入整个Parse。那些动辄引用com.parse:parse-android的教程多半是远古时期的写法千万别学。单独依赖bolts-tasks即可包体小、无副作用。3.2 封装一个带进度回调的下载/初始化TaskRN原生模块里最常见的一个需求是“初始化信息加载”比如App启动后要从本地数据库读取配置、从系统读取设备参数再把状态回传给JS侧。这个过程既有耗时操作又有失败分支还要考虑进度反馈。我封装过一个简单的初始化模块代码结构大概是这样的// DeviceInitModule.java public class DeviceInitModule extends ReactContextBaseJavaModule { private final ReactApplicationContext reactContext; public DeviceInitModule(ReactApplicationContext reactContext) { super(reactContext); this.reactContext reactContext; } Override public String getName() { return DeviceInitModule; } ReactMethod public void startInit(Promise promise) { // 1. 读取本地缓存配置 TaskJSONObject configTask Task.callInBackground(new CallableJSONObject() { Override public JSONObject call() throw Exception { return loadConfigFromCache(); } }); // 2. 获取系统设备信息 TaskJSONObject deviceInfoTask Task.callInBackground(new CallableJSONObject() { Override public JSONObject call() throws Exception { return collectDeviceInfo(); } }); // 3. 合并两个Task结果组成初始化数据 Task.whenAll(Arrays.asList(configTask, deviceInfoTask)) .continueWith(new ContinuationListObject, JSONObject() { Override public JSONObject then(TaskListObject task) throws Exception { if (task.isFaulted()) { throw task.getError(); } JSONObject result new JSONObject(); JSONObject config (JSONObject) task.getResult().get(0); JSONObject deviceInfo (JSONObject) task.getResult().get(1); result.put(config, config); result.put(deviceInfo, deviceInfo); // 在这里可以向JS侧发送进度事件 sendProgressEvent(init_completed); return result; } }) .continueWith(new ContinuationJSONObject, Void() { Override public Void then(TaskJSONObject task) { if (task.isFaulted()) { // 把原生异常转成JS可读的Error promise.reject(INIT_ERROR, task.getError()); } else { promise.resolve(task.getResult()); } return null; } }); } private void sendProgressEvent(String status) { WritableMap params Arguments.createMap(); params.putString(status, status); reactContext.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class) .emit(onDeviceInitProgress, params); } }RN侧调用就很简单了import { NativeModules, DeviceEventEmitter } from react-native; const { DeviceInitModule } NativeModules; DeviceEventEmitter.addListener(onDeviceInitProgress, ({ status }) { console.log(初始化进度:, status); }); try { const initData await DeviceInitModule.startInit(); console.log(初始化数据:, initData); } catch (e) { console.warn(初始化失败:, e.message); }这个模块把两个独立的异步任务并发执行等两个结果都回来再合并给JS侧。如果本地缓存读取或设备信息获取挂了JS侧能立刻收到reject不会出现白屏等半天的情况。3.3 把Bolts Task桥接给JS Promise需要说明的是RN的Promise参数本身就是一个回调封装原生侧在任意时刻调用promise.resolve(data)或promise.reject(error)JS侧对应的await就会结束。所以桥接的核心就一句话在Bolts Task的延续回调里调用promise的resolve或reject。上面代码已经展示了这个套路。有几点要注意在ReactMethod的方法参数里Promise必须放在最后一位。同一个Promise只能resolve或reject一次如果Bolts的延续逻辑可能触发多次回调要加防重入判断。不要在Task内部直接调用promise.resolve后又调promise.rejectJS侧会忽略第二次但日志里会有警告。如果需要把多个不同的Task结果分别回传给JS侧比较推荐的做法是用DeviceEventEmitter发事件而不是依赖单一的Promise。Promise适合“一次请求一次结果”的场景事件适合“进度反馈”的场景两者搭配使用体验最好。我在项目里把“进度条”和“Promise”结合起来用Promise负责最终结果的resolve/reject进度事件负责中间过程展示这样JS侧既能拿到最终数据也能实时更新UI不会出现整个过程UI一动不动的情况。3.4 实战串行初始化解决启动白屏启动白屏是RN应用常见问题之一根因往往是JS侧在等待原生侧完成某些初始化而原生侧给不到反馈或反馈太慢。如果用Bolts把“串行初始化流程”拆成几步链式Task每一步都带超时保护白屏问题会好很多。举个例子启动时要依次完成读取本地配置 - 检查权限 - 初始化地图SDK - 获取用户信息。前一步的成功结果要作为后一步的输入典型的串行依赖。用Bolts写Task.callInBackground(new CallableLocalConfig() { Override public LocalConfig call() throws Exception { return loadLocalConfig(); } }).onSuccess(new ContinuationLocalConfig, TaskBoolean() { Override public TaskBoolean then(TaskLocalConfig task) { LocalConfig config task.getResult(); return checkPermissionAndPrompt(config.needPermission); } }).onSuccess(new ContinuationBoolean, TaskBoolean() { Override public TaskBoolean then(TaskBoolean task) { return initMapSdk(); } }).continueWithTask(new ContinuationBoolean, TaskUserInfo() { Override public TaskUserInfo then(TaskBoolean task) throws Exception { if (task.isFaulted() || !task.getResult()) { // 地图SDK初始化失败不阻塞启动返回一个匿名用户信息 return loadUserInfoAnonymously(); } return loadUserInfo(); } }).continueWith(new ContinuationUserInfo, Void() { Override public Void then(TaskUserInfo task) { if (task.isFaulted()) { promise.reject(BOOTSTRAP_ERROR, task.getError()); } else { promise.resolve(task.getResult().toMap()); } return null; } });这里使用了continueWithTask它的延续函数返回的是一个新的TaskBolts会自动等待这个新Task完成后再进入下一步。链式流程里每一步的超时也可以用.withTimeout(...)包一层避免某个第三方SDK初始化卡死。这种方式比“把整个初始化流程塞进一个Callable里”强在哪第一每步拆开可以在延续里打印日志问题定位快第二失败分支细化某一步失败可以选择“降级继续”还是“终止启动”第三线程模型更可控耗时步骤放后台回调UI线程由Executor控制。实际项目里用了这套之后启动白屏的投诉确实少了因为JS侧至少能在超时后收到一个Error而不是永远处于pending状态。4. 踩坑记录与问题排查4.1 线程模型Bolts延续究竟跑在哪条线程这是Bolts新手最容易踩的坑。默认情况下task.continueWith(...)的延续代码会在“调用continueWith的那条线程”上执行而不是像JS Promise那样自动回到某个固定线程。如果你在某个后台线程里调用了continueWith那么延续也在这个后台线程跑如果你在UI线程调用延续就在UI线程跑。RN模块的场景里这带来两个问题如果后台Task完成后延续代码被调度到后台线程执行但延续里访问了RN的Promise.resolve这个问题倒不大因为Bridge内部会处理线程切换。如果延续里要做SharedPreferences写操作或网络请求线程很容易用错偏偏Bolts又不强制你传Executor所以代码就会在“看似正确的随机线程”上跑。我的建议是凡是涉及到RN JS通信的延续统一指定UI线程执行器HandlerExecutor uiExecutor new HandlerExecutor(new Handler(Looper.getMainLooper())); task.continueWith(new ContinuationObject, Void() { Override public Void then(TaskObject task) { // 这里保证在UI线程执行 promise.resolve(result); return null; } }, uiExecutor);HandlerExecutor是Bolts库自带的一个Executor实现内部就是Handler包装用法简单。如果不想依赖这个类也可以直接用Android的Handler自己包一个Executor。线程问题排查时优先检查所有continueWith/onSuccess有没有传Executor尤其不要在后台线程里擅自更新UI。4.2 内存泄漏与引用释放Bolts的Task链会持有Continuation对象的引用Continuation作为匿名内部类会持有外部类实例的引用。如果RN模块里写了一个长耗时的Task并且模块实例迟迟不被释放就会造成内存泄漏。我遇到过的场景是页面销毁后后台Task还在跑延续里又访问了被销毁页面的Context直接导致崩溃。解决方式有两个一个是在页面销毁时通过CancellationTokenSource取消任务另一个是延续回调里用WeakReference包裹外部引用。new ContinuationObject, Void() { Override public Void then(TaskObject task) { WeakReferenceActivity weakActivity new WeakReference(activity); Activity ref weakActivity.get(); if (ref null) { return null; } ref.runOnUiThread(() - { // 更新UI }); return null; } }RN的ReactApplicationContext本身生命周期比较长一般不会随便被销毁但如果你在模块内部持有Activity或Fragment引用就要格外小心。4.3 与RN Bridge/TurboModule的兼容性如果你在用新架构TurboModuleBolts依然可用因为它只是在Java层做任务编排跟RN的JS/Native通信方式解耦。你只需要把Bolts的Task结果在模块方法里通过CallBack或Promise返回即可TurboModule的com.facebook.react.bridge.Promise签名和旧版一样。需要注意的一个兼容性问题是依赖冲突。Bolts和部分第三方Android库可能存在同名类比如某些SDK内部也用了bolts.task.Task。我在一个项目里遇到过引入两个不同版本Bolts导致的类冲突表现是ClassCastException或者NoSuchMethodError。排查方法很简单看Gradle依赖树用gradle dependencies查出哪个库带入了旧版Bolts排除掉多余的那个implementation(com.example:some-sdk:1.0) { exclude group: com.parse.bolts }RN生态里做App Links和Deep Link的库最喜欢带Bolts依赖如果你只是用bolts-tasks记得检查最终打包里只有一个版本的Bolts。混淆规则上Bolts一般不需要特殊处理但如果你开启严格混淆建议保留com.parse.bolts.**的类名避免连续Lambda的反射问题。4.4 常见问题速查表症状可能原因解决办法JS侧Promise一直pending原生侧Task没有完成或者promise.resolve没被调用用withTimeout包Task延续里print日志确认是否到了resolve代码延续代码在错误的线程执行没传Executor或传错了Executor需刷新UI或调Promise时用HandlerExecutor绑定主线程异常被吞掉Task处于faulted但不确定原因延续里漏了task.isFaulted()检查在onSuccess里判断isFaulted打印task.getError()出现ClassCastExceptionBolts版本冲突或泛型强制转换出错gradle dependencies查重核对Task 泛型多个初始化Task并发时一个失败拖垮整体whenAll的语义就是全部成功才算成功在每个子Task里捕获异常返回默认值或改用whenAnyResult内存泄漏Continuation持有Activity引用用WeakReference包裹外部引用页面销毁时取消Task这些坑很多都是“用到第N次才反应过来”尤其线程和异常吞掉这两个几乎每个RN原生模块开发都会遇到。排查思路总是一样先看Task状态是faulted还是completed再定位延续在哪条线程执行。把这两个锚点抓住Bolts相关问题就解决了一大半。5. 写在最后的体会从第一次在RN项目里引入Bolts到现在我对这个库最大的感受是它解决的不是“功能问题”而是“代码组织问题”。异步逻辑一旦被Task链理顺读代码和改代码的体验都好了不止一个档次。尤其是RN原生模块这种跨桥接场景异步任务的可读性直接决定了后续维护成本。最后分享一个小技巧如果你在RN模块里发现自己频繁写“回调套回调”先不要急着加RxJava或协程花半小时试试Bolts。它不是什么花哨的新技术但对“把系统异步API包装成Promise”这件事来说它是目前我试过最省心的方案。而且Bolts的代码量很小通读一遍源码也不难理解之后就再也不会写出拆不开的异步面条了。