1. 项目概述与核心场景定位1.1 Bolts在React Native 生态里的“隐身”地位很多做React Native开发的同学尤其是刚接触Android原生模块的人第一次听说Bolts往往是在翻node_modules里的react-native源码时看到的。你可能会有个疑问一个做异步任务的Java库跟跨端框架有什么关系我先说结论Bolts是Facebook早期开源的一个底层任务库它解决的问题非常朴素——把Android原生层里乱七八糟的异步回调改造成可以链式调用、可以组合、可以复用的Task对象。在React Native的Android端它主要负责桥接层Bridge里那些需要跨线程、跨模块协作的脏活累活比如native module里发起网络请求、读写文件、操作数据库、等待某个初始化流程完成之后再回调JS层。我最早接触Bolts是在做一个RN项目的原生端改造时有个需求是从相册选完图后需要依次做压缩、旋转校正、上传最后再把结果回调给JS层。原本的代码是三层嵌套回调加上线程切换逻辑乱得没法看。后来发现React Native自己就在用Bolts干脆把它拿出来单独用整个链路瞬间清爽。这也是这篇博文想做的事把Bolts从RN的“内部依赖”里拎出来讲讲它到底是什么、怎么用、用在RN原生模块开发里有哪些实战价值。1.2 它解决的真实痛点是什么RN的Android开发里原生模块NativeModule经常要处理异步任务比如从content://协议的Uri读取文件并做拷贝将长图片压缩到目标尺寸分页查询本地数据库并逐批返回多个初始化任务并行执行全部完成后再通知JS层需要实时上报进度的耗时操作比如大文件上传。这些任务如果用传统的Callback接口写基本逃不过三个问题回调地狱、线程切换混乱、异常处理碎片化。你需要在UI线程、IO线程、JS线程之间来回跳还要到处try-catch一旦某个回调分支忘记处理线上就会冒出诡异的线程异常。Bolts的价值在于把异步链路的“控制流”抽出来用类似JavaScript里Promise的写法组织Java代码。它不关注你的业务是什么只负责把“这件事做完了”和“这件事失败了”这两种状态串联起来。提示Bolts并不是React Native首创或独有的它在Facebook的Android应用如早期的Facebook App里就大量使用。RN只是把它作为一个基础库打包了进来。所以你完全可以脱离RN在任何Android项目里使用Bolts它的依赖只有一个体积很小。2. 核心机制拆解Task、Executor与延续模型2.1 从一个简单Task说起你在RN的Android源码里最常见的Bolts用法是类似这样的Task.callInBackground(new CallableString() { Override public String call() { return doSomeHeavyWork(); } });这行代码干了什么它在后台线程池里执行了doSomeHeavyWork()然后返回一个TaskString。这个Task可以理解为“未来的结果”它有三种状态Pending进行中、Completed成功完成带结果、Faulted失败带异常。这个设计在概念上并不新鲜但Bolts有一个特性很值得注意它不规定你必须在哪个线程创建Task也不强制你在哪个线程处理结果。每个Task都可以挂一个Continuation延续你可以指定它跑在哪个Executor上这在RN的场景里非常关键因为JS线程、UI线程、native工作线程各有各的限制。2.2 Continuation链式调用的灵魂链式调用是Bolts最吸引人的地方。你不需要一层层嵌套回调只需要把下一步要干的事作为Continuation挂上去Task.callInBackground(new CallableString() { Override public String call() throws Exception { return readFileFromUri(uri); // 步骤1读取文件 } }).continueWith(new ContinuationString, String() { Override public String then(TaskString task) throws Exception { return compressImage(task.getResult()); // 步骤2压缩 } }).continueWith(new ContinuationString, Boolean() { Override public Boolean then(TaskString task) throws Exception { return uploadFile(task.getResult()); // 步骤3上传 } }, Task.BACKGROUND_EXECUTOR);这个链路的可读性比回调嵌套高了一个数量级。每个then方法的入参是上一个Task你可以通过task.getResult()取结果也可以通过task.isFaulted()判断失败然后把这个Task继续往下传。这里有个细节值得解释Continuation的返回值会决定下一个Task的状态。如果then返回一个普通对象Bolts会把它包装成一个成功的Task如果then抛出异常Bolts会生成一个Faulted的Task传给下一步。这意味着你不需要在每个环节都写try-catch只要在链路的末端统一处理错误即可。2.3 为什么RN选它而不是纯Java回调从RN源码看ReactContext、NativeModule的许多公共方法直接或间接依赖Bolts的Task。比如React Native的NativeModuleRegistry在初始化模块时需要保证所有native模块都ready之后才通知JS层这个逻辑如果用CountDownLatch或回调数组写会很别扭。Bolts的Task.whenAll()可以干净地解决ListTaskVoid taskList new ArrayList(); for (NativeModule module : modules) { taskList.add(module.initialize()); } TaskVoid allTask Task.whenAll(taskList); allTask.continueWith(new ContinuationVoid, Void() { Override public Void then(TaskVoid task) { // 所有模块初始化完成 return null; } });在RN的Android架构里这属于“基础设施”级别的东西。虽然大多数业务开发不会直接碰它但理解这个机制对排查RN启动白屏、模块初始化缓慢这类问题非常有帮助。白屏场景的一个典型例子JSBundle里的AppRegistry.runApplication执行前native侧需要确保一些模块比如NativeAnimatedModule、FrescoModule初始化完毕并且所有待处理的消息已经flush。如果某些模块的初始化Task因为异常进入了Faulted状态而又没有正确的错误兜底JS层一直等不到callback表现就是白屏。这时候如果会看Bolts的Task状态排查效率会高一截。3. 实战准备在你的Android工程里引入Bolts3.1 集成方式一通过Gradle直接依赖如果你是纯Android工程或RN项目里的native部分想单独复用Bolts最直接的方式是加依赖。implementation com.parse.bolts:bolts-tasks:1.4.0这是Bolts官方发布到Maven Central的最后一个稳定版本坐标是com.parse.bolts:bolts-tasks:1.4.0注意bolts-tasks是纯任务库bolts-applinks才是处理App Links的模块别引错。如果你的工程还同时依赖了bolts-android这个老坐标最好统一成上面的形式避免版本冲突。3.2 集成方式二复用React Native自带依赖如果你只是在自己的RN项目里写native代码不需要额外引入依赖因为RN已经帮你带上了Bolts。但你需要在ProGuard规则里留意它-keep class bolts.** { *; }为什么因为Bolts的Task在链式调用时Continuation经常以匿名内部类的形式使用反射或混淆不当容易出问题。我在release包上遇到过Continuation的then方法签名被混淆成奇怪名字导致运行时无法回调的坑加了keep规则之后才稳定。3.3 它跟RxJava怎么选很多人会问Bolts能干的活RxJava也能干而且还更强为什么RN偏偏选Bolts答案很务实体积和时间。Bolts的tasks模块只有几十个类核心类不超过10个而RxJava的依赖链庞大得多。对于RN这种“要打包进APK、启动时要加载大量类”的场景Bolts足够轻量且完全能满足桥接层99%的异步需求。如果你在RN原生模块里为了用RxJava而引入一大坨依赖反而加重了包体积和初始化耗时。实操心得如果你的Android原生模块项目里已经用了RxJava我不建议强行“去Rx化”换Bolts。但如果你只是在RN bridge层写点异步任务Bolts更轻、更合适。二者不是非此即彼的对立关系Bolts解决的是“基础任务编排”RxJava更偏向于“响应式数据流”。RN的内部代码选择了前者我们做原生扩展时也尽量遵循这个约定减少不必要的复杂度。4. 核心实操在RN原生模块中用Bolts处理真实业务4.1 场景一从Uri读取文件并回调JS层RN开发中经常遇到一个问题JS层拿到的是content://协议的Uri比如从相册选择图片后得到的Uri。你需要在native层把Uri转成实际文件、做压缩再返回base64或本地路径。这里边就涉及内容提供器的权限、IO线程、回调JS线程的切换。下面我用Bolts实现一个典型的“读取并拷贝文件”模块。public class FileHandleModule extends ReactContextBaseJavaModule { ReactMethod public void copyUriToCache(String uriString, Promise promise) { Task.callInBackground(new CallableString() { Override public String call() throws Exception { Uri uri Uri.parse(uriString); ContentResolver resolver getReactApplicationContext().getContentResolver(); String displayName queryDisplayName(resolver, uri); File cacheDir getReactApplicationContext().getCacheDir(); File targetFile new File(cacheDir, displayName); try (InputStream input resolver.openInputStream(uri); OutputStream output new FileOutputStream(targetFile)) { byte[] buffer new byte[8192]; int len; while ((len input.read(buffer)) ! -1) { output.write(buffer, 0, len); } } return targetFile.getAbsolutePath(); } }).continueWith(new ContinuationString, Void() { Override public Void then(TaskString task) { if (task.isFaulted()) { promise.reject(COPY_FAILED, task.getError()); } else { promise.resolve(task.getResult()); } return null; } }, UiThreadExecutor.getInstance()); } }这里有个非常关键的点promise的回调线程。RN的Promise虽然可以在任何线程调用但底层最终会跨过bridge转发到JS线程。如果你在后台线程直接resolve虽然能工作但某些版本的RN会有时序问题。比较稳的方式是把Continuation指定到UI线程执行再调用promise的resolve/reject。我这里写了一个UiThreadExecutor大家可以用Task.UI_THREAD_EXECUTORBolts自带代替。还有一个细节如果你的模块里同时处理多个Uri建议用Task.whenAll()并行处理全部完成后再一次性回调能明显减少桥接层的往返开销。4.2 场景二耗时任务上报进度很多业务需求里JS层需要知道一个耗时native任务的进度比如压缩了多少、上传了多少。Bolts本身没有内置“进度回调”的概念但你可以组合AsyncTask风格的逻辑。一个比较实用的做法是定义ProgressTask内部持有AtomicInteger或volatile变量在工作线程更新进度同时在另一个周期性的Task里把进度回传到JS层。public TaskString doHeavyWorkWithProgress(final ProgressCallback callback) { final AtomicInteger progress new AtomicInteger(0); return Task.callInBackground(new CallableString() { Override public String call() throws Exception { for (int i 0; i 100; i) { Thread.sleep(50); // 模拟耗时操作 int current progress.incrementAndGet(); if (current % 10 0) { callback.onProgress(current); } } return done; } }); }这个思路本身不新颖但放在RN桥接层有一个性能上的取舍提醒不要每个进度都回调JS。React Native的bridge是异步消息通道高频次地批量回调会把JS线程塞满导致UI掉帧。我一般会把进度按5%~10%的粒度上报必要时配合InteractionManager或requestIdleCallback错峰发送。这个坑我在一个视频导出功能里踩过进度回调太频繁JS侧渲染进度条反而卡顿肉眼可见地不流畅。4.3 场景三多Task并行与结果聚合假设你要在启动App时并行加载三个native配置读本地JSON配置、从数据库拉用户偏好、检查网络状态。三个任务互不依赖全部完成后把结果拼成一个Map回传JS。TaskString loadLocalConfig Task.callInBackground(...); TaskMapString, Object loadUserPrefs Task.callInBackground(...); TaskBoolean checkNetwork Task.callInBackground(...); Task.whenAll(loadLocalConfig, loadUserPrefs, checkNetwork) .continueWith(new ContinuationVoid, String() { Override public String then(TaskVoid task) { if (task.isFaulted()) { return handlePartialResult(); } MapString, Object result new HashMap(); result.put(config, loadLocalConfig.getResult()); result.put(prefs, loadUserPrefs.getResult()); result.put(network, checkNetwork.getResult()); String json new Gson().toJson(result); promise.resolve(json); return json; } });注意这里whenAll返回的Task本身不携带所有子Task的结果你需要分别从原来的Task里getResult()这逻辑上有点绕但很直观。因为每个子Task都已经是completed状态直接取不会阻塞。4.4 场景四无来源FileProvider路径处理热词里出现了一大堆content://相关的异常路径比如content://com.baidu.searchbox.fileprovider/baiddpath/android/data/com.ba、content://com.tencent.wework.fileprovider/external_path/android/data/com这些其实是Android的文件共享Uri在跨应用传递时被截断或拼接错误导致的。你在RN里收到这类Uri时如果直接用new File(uri.getPath())大概率找不到文件。正确姿势是全部走ContentResolver绝不要手动拼接路径。先用resolver.getType(uri)判断MIME类型再用openInputStream读取。如果遇到没有权限的Uri还要先尝试takePersistableUriPermission需要用户在文件选择器里授权。Bolts在这里的作用是把“检测权限→申请权限→打开流→读取→复制”这几个步骤串成一条清晰的Task链任何一个环节失败都能被精确捕获而不是散落在各个回调里成为悬空异常。5. 进阶玩法与源码级理解5.1 Task的取消与继续延续Bolts有个不那么显眼但非常实用的特性每个Task可以携带一个CancellationToken。RN的原生模块里如果你启动了一个耗时很长的任务比如把大文件从缓存目录拷贝到外部存储用户可能在任务执行途中退出页面这时候你就需要取消机制。CancellationTokenSource cts new CancellationTokenSource(); TaskString task Task.callInBackground(..., cts.getToken()); // 在某些时机调用 cts.cancel();但要注意Bolts的取消不是“强制中断线程”它只是在任务开始执行前或阶段切换时检查token状态。如果你的Callable本身是个阻塞的IO操作cancel并不会立刻杀掉它需要在代码里主动检查token.isCancellationRequested()。我做RN原生数据库导出功能时用这个机制实现了“用户点击取消则停止导出并清理临时文件”的效果。实测下来虽然不如RxJava的dispose那么“暴力”但在Java层已经算很够用的协作式取消了。5.2 从RN的源码看Bolts的用法约定RN的ReactAndroid源码里NativeModuleRegistry初始化时有一个notifyJSInstanceInitialized方法它内部会用Task来做模块就绪的通知链。你如果扒开来看会发现它对Continuation的线程选择非常讲究有的放在CATALYST_THREAD有的放在UI_THREAD有的放在BACKGROUND_EXECUTOR。这就是Bolts第二个精髓——线程模型交给了调用者而不是固定在线程池里。这种设计对RN有个直接好处JS线程的响应性不会被native层的IO拖累同时UI操作可以安全地切回UI线程执行。理解了这一点你在自己写原生模块时就知道什么时候该指定Task.BACKGROUND_EXECUTOR什么时候该用Task.UI_THREAD_EXECUTOR。5.3 自定义Executor控制线程池大小RN环境下如果你在一个原生模块里用Task.callInBackground发起大量短时任务默认的Executors可能会创建很多线程这对中低端Android设备并不友好。Bolts允许你自己传入ExecutorExecutorService executor Executors.newFixedThreadPool(4, new ThreadFactory() { Override public Thread newThread(Runnable r) { Thread t new Thread(r, rn-bolts-worker); t.setPriority(Thread.NORM_PRIORITY - 1); return t; } }); Task.callInBackground(callable, executor);这个在上传大图、批量处理缩略图的场景里特别有用。固定线程池可以限制并行度低优先级可以避免抢占UI绘制线程。曾经有次我用默认配置并发处理20张图片结果线程数飙到三十多个老机型直接卡顿改成固定4线程后流畅度明显好转而且整体耗时只多了10%左右性价比很高。6. 常见问题与排查技巧实录6.1 链式调用里Continuation不执行现象continueWith挂上去但断点不进then方法。排查思路先看前面的Task是不是处于Faulted状态。如果前一个Task抛了异常而你没有调用continueWith的Task对象检查返回值异常可能被吞掉。在then方法里第一时间加一行if (task.isFaulted()) Log.e(TAG, task.getError());通常能快速定位。另一个常见原因你在方法里创建了Task局部变量但方法结束前Task还没来得及完成Continuation被GC了。解决方法是把Task对象持有在类的成员变量上特别是在RN的ReactMethod里局部变量生命周期短容易出现这种问题。6.2 Promise回调在UI线程执行的隐患现象在UI线程的Continuation里执行promise.resolve()偶尔出现崩溃或JS侧拿到数据未及时刷新UI。分析RN的Promise在Android端是通过回调Id发到JS线程的UI线程resolve本身不一定会崩溃但如果你在resolve之前做了耗时操作比如JSON序列化大对象会卡掉UI线程的绘制。稳妥的做法是耗时操作放在后台线程最终resolve之前把数据准备好再切到UI线程只做“提交结果”这一个轻量动作。实操心得在RN桥梁里的Promise操作我统一遵守一个原则“CPU密集工作放后台轻量线程切换放UI”。这个原则在Bolts的链式调用里很容易落地——你只需要给不同环节的Continuation指定不同的Executor就能做到“计算后台化、回调UI化”。6.3 多模块初始化时使用whenAll但仍有白屏现象用whenAll等所有native模块初始化但JS首屏偶尔还是白屏。排查思路whenAll只保证Task完成不保证“完成后JS消息已经消费”。在RN启动流程中notifyJSInstanceInitialized发出后JS层还要处理一堆挂载逻辑。白屏更常见的原因是JS侧渲染所需的native模块没准备好而不是Bolts本身的问题。经验是用Bolts去串“原生初始化”没问题但排查白屏时要往JS层的AppRegistry.runApplication调用时机、Bundle加载耗时、首帧渲染资源这几个方向去看别只盯着Task链路。6.4 常见问题速查表现象可能原因解决方案Continuation不执行前置Task处于Faulted状态在then入口判断isFaulted并打日志Task对象被提前回收局部变量持有Task改为类成员变量或静态变量持有Promise回调偶发崩溃resolve在后台线程且数据量大数据序列化后切UI线程resolve并发任务导致设备卡顿默认线程池创建太多线程自定义固定大小线程池并降低线程优先级release包链式回调失效ProGuard混淆了Continuation添加keep规则保留bolts包6.5 与React Native新架构的兼容性RN新架构Fabric/TurboModule里原生模块的调用方式有了很大变化但Bolts并没有被弃用反而在bridge与turbomodule的兼容层里继续存在。如果你在老架构里用Bolts写的模块迁移到新架构大多数逻辑不用改因为Bolts解决的是“Java层异步任务编排”这跟桥接层用什么协议无关。不过有一点值得注意新架构下JS调用native方法的RPC往返更快对任务并发的需求也在增加Bolts的线程模型建议更激进地使用BACKGROUND_EXECUTOR避免把耗时任务塞在JS调用线程里。7. 热词场景联动Android 16适配、Android Studio环境与动态图标7.1 Android 16V的Uri读写权限趋势评论区里那些content://com.tencent.mobileqq.sharefileprovide/external_files/android/d之类的Uri路径在Android 16API level 36上会越来越少见因为系统在强化“分区存储”和“运行时Uri授权校验”。如果你的RN原生模块还在用File直接访问外部路径大概率会碰到FileNotFoundException或SecurityException。Bolts在这里的价值是它天然适合把“Uri授权检查”作为一个前置Task失败时直接走Faulted分支你可以在错误处理器里弹出系统文件选择器让用户重新授权授权完成后再重试后续Task。这种流程用纯回调写起来十分痛苦但用Bolts的continueWith会自然很多。7.2 Android Studio环境准备中的Bolts定位在使用Android Studio调试RN原生模块时很多人会遇到Gradle同步失败或依赖冲突。如果你手动引入Bolts最典型的冲突是重复类——RN内部已经包含了bolts-tasks你再在app/build.gradle里加一遍会导致Duplicate class。解决办法很简单只在自研纯Java module里引app模块不要重复引或者用compileOnly声明。我在Android Studio里调试Bolts链路时习惯在关键Continuation的then方法里打点日志配合adb logcat过滤bolts关键字。Bolts的源码里本来就有一些debug日志开关你可以通过Task.DEBUG true开启。7.3 RN启动白屏与Bolts的关联排查RN启动白屏是热词里反复出现的高频问题。虽然白屏的原因有很多但如果你用Bolts在Application或MainActivity的onCreate里做了初始化任务白屏可能就跟这些Task的执行顺序有关。典型场景MainActivity的onCreate里有一个用Bolts发起的异步加载加载过程中RN的ReactRootView已经创建但startReactApplication还没执行JS侧没拿到初始化数据首屏就空白。这时需要保证“JSBundle加载完”和“异步数据准备好”两个条件都满足后再渲染可以借助Task.whenAll()把两个Task合并成一个启动门闩白屏问题会减轻不少。8. 写在最后的一点个人经验这篇文章从RN视角把Bolts的定位、核心机制、实践场景和排查技巧都过了一遍最后分享一个我用了很久的小技巧在调试原生模块时可以给Bolts的Task挂一个统一的错误日志Continuation就像这样TaskVoid loggingTask task.continueWith(new ContinuationVoid, Void() { Override public Void then(TaskVoid task) { if (task.isFaulted()) { Log.e(RN-Bolts, Task failed, task.getError()); } return null; } });把它放在调试开关里release版本关掉成本几乎为零但在开发期能省下非常多排查时间。Bolts这个库看着不起眼但它是RN原生层稳定性的一个基石搞懂它你在做RN的Android扩展时很多异步难题都能迎刃而解。