RN原生模块通信：Callback与Promise回传机制解析

我在做供应链App的时候接过一个蓝牙打印的SDK，设备扫描、连接状态、打印结果这些全在原生层，数据拿回来之后怎么“递”给RN的JS页面，那段时间真是踩坑踩到头皮发麻。后来把整套机制理清楚之后发现，核心问题其实就是一件事：原生代码通过callBack或Promise调用RN代码。今天这篇文章就是这个过程的完整复盘，把Android和iOS两端的实现方式、选型逻辑、以及我实际踩过的坑全部摊开讲，给正在做RN原生混合开发的朋友一份能直接抄作业的参考。

1. 为什么原生层结果回传JS层是个绕不开的问题

1.1 最典型的业务场景：扫描、打印、设备状态

就以我当时的项目为例，业务流程是这样的：JS页面点一个“开始打印”按钮，RN调用原生模块的startScan方法，原生层开始扫描蓝牙设备；扫到设备后，原生层要把设备列表、信号强度、连接状态回传给JS层，JS层展示给用户；用户选择设备后，再调connectDevice，连接结果又要回传；连接成功后调print，每张纸的打印进度、缺纸状态、完成回调都要回传。这一整套流程，没有一次是原生方法同步返回就能搞定的。

这其实是RN混合开发的常态，凡是涉及硬件操作、系统能力、第三方SDK的，原生方法基本都是异步的，执行结果只能在“将来的某个时刻”产生。JS发起调用之后，需要有一种机制，让原生层在结果准备好的时候反向通知JS。Callback和Promise，就是这种“反向通知”的官方通道。

1.2 RN原生通信的基本脉络：JS不能直接等结果

很多人刚开始写原生模块时会有一个错觉：在原生方法里写个return result，JS端不就能拿到了？这里必须先把原理讲透。RN的JS和原生通信不是同一个线程间的普通函数调用，而是通过Bridge（新架构里是TurboModule + JSI）进行的消息传递。

JS调用原生方法，实际上是往Bridge一侧发送了一个消息，原生模块在这个消息里找到对应的方法并执行。默认情况下，这个执行过程是异步的，原生方法执行完的那一刻，JS侧的调用栈早就不知道跑到哪里去了，压根不存在“同步return返回”这条路。唯一的例外是isSync方法，但官方明确不建议大量使用，因为它会阻塞JS线程，只适合拿到一个立即返回值的极小场景。

所以，原生方法要回传结果，只能走“把回调函数传给原生”的路子。这个回调函数有两种格式，一种是Callback，一种是Promise。理解了这一点，后面所有代码就都顺了。

2. Callback方式：原生层“打电话”把结果送回去

2.1 Android端Callback实现：从Callback到invoke

Android端要写一个带Callback的原生模块，代码结构是这样的：

java复制public class PrinterModule extends ReactContextBaseJavaModule {

    @Override
    public String getName() {
        return "PrinterModule";
    }

    @ReactMethod
    public void scanDevices(Callback successCallback, Callback errorCallback) {
        try {
            List<DeviceInfo> devices = doScan();
            // 把对象转成WritableMap再传给JS
            WritableArray result = Arguments.createArray();
            for (DeviceInfo device : devices) {
                WritableMap map = Arguments.createMap();
                map.putString("deviceName", device.getName());
                map.putString("deviceId", device.getAddress());
                map.putInt("rssi", device.getRssi());
                result.pushMap(map);
            }
            successCallback.invoke(result);
        } catch (Exception e) {
            errorCallback.invoke(e.getMessage());
        }
    }
}

关键点在这个successCallback.invoke(result)。invoke方法的所有参数，会被RN框架打包成一个数组，通过Bridge传递到JS侧。JS端的回调函数形参，就对应invoke传入的各个参数。比如上面写了successCallback.invoke(result)，JS端回调的第一个参数拿到的就是这个result数组；如果写successCallback.invoke(code, message, data)，那JS回调就能收到三个参数。

测试一个新模块好不好使，最快的办法是先用简单的参数类型试。比如先successCallback.invoke("hello")，JS端console.log(ret)能看到字符串，再逐渐上复杂类型。直接上WritableMap如果字段类型不对，很容易在调试期才暴露。

2.2 iOS端Callback实现：RCTResponseSenderBlock

iOS端的实现思路完全一致，只是API换成了RCTResponseSenderBlock：

objc复制RCT_EXPORT_METHOD(scanDevices:(RCTResponseSenderBlock)successCallback
                  errorCallback:(RCTResponseSenderBlock)errorCallback)
{
  NSError *error = nil;
  NSArray *devices = [self doScanWithError:&error];
  if (error) {
    errorCallback(@[error.localizedDescription]);
  } else {
    successCallback(@[devices]);
  }
}

这里有个极其容易踩的坑：RCTResponseSenderBlock接收的参数必须是一个NSArray，即使你只想回传一个值，也得用@[value]包一层。对应到JS端，回调函数拿到的第一个参数就是这个数组的第一个元素。很多新手直接在successCallback(devices)，结果JS端收到的永远是一个嵌套数组，解析老是为空，还以为是数据问题。

我从这个坑里形成的习惯是：在iOS端回调时，明确用@[result]包数组，在JS端再用一次[result]的解构或者直接取第一个参数，两头对齐，不猜。

2.3 JS端收Callback的正确姿势

JS端调用带Callback的原生方法，写法很直接：

js复制import { NativeModules } from 'react-native';

const { PrinterModule } = NativeModules;

PrinterModule.scanDevices(
  (devices) => {
    console.log('扫描到设备：', devices);
    setDeviceList(devices);
  },
  (error) => {
    console.error('扫描失败：', error);
  }
);

这段代码看起来简单，但有几个隐含的行为要说清楚。第一，Callback是“一次性”的，原生端调用一次invoke之后，这个回调就失效了，不能重复触发。第二，Callback的执行环境不在JS发起调用的那个上下文里，而是由原生端控制的线程。原生端如果在非主线程调用invoke，JS端接收时通常没有问题，但如果接下来要更新状态，React组件的setState依然得在React的调度机制下走，原生回调本身不会帮你回到JS线程。

所以我在实际项目里，只要Callback回调里涉及setState、导航、弹窗这类UI操作，都会在原生端明确处理好线程，或者在JS端用InteractionManager.runAfterInteractions包一层，避免UI更新时机不对造成白屏或卡顿。

2.4 Callback方式的三个专属雷区

第一个雷区：Callback参数个数不对称。Android端的invoke和iOS端的@[]数组，参数数量必须和JS端回调函数的形参数量对应。多传了，JS端拿不到；少传了，JS端多出来的形参是undefined。

第二个雷区：Callback只能触发一次，但原生端代码写得不严谨时，同一个Callback可能被调用两次。比如你在一次方法里同时调用了successCallback和errorCallback，JS端就会收到两次回调，第一次执行成功逻辑，第二次又走错误逻辑，页面上数据就会出现“先有数据、后报错”的诡异现象。在原生端做好出口守卫是必须的，我通常会在类里加一个isCallbackInvoked的布尔标记。

第三个雷区：原生对象作为参数直接传入Callback，JS端不一定能正确解析。必须用Arguments.createMap()、Arguments.createArray()这类RN提供的可写数据结构，普通Java对象是不行的。服务端返回的JSON结构，建议在原生端解析好后，直接用WritableMap组织好再传，不要在JS端再做一次繁琐的字段映射。

3. Promise方式：更优雅的异步契约

3.1 Promise原理一句话讲清楚

Promise不是RN特有的东西，它是ECMAScript的异步标准，核心就三点：一是Promise对象在创建时接收一个执行器函数，这个函数内部进行异步任务；二是异步任务完成时调用resolve把状态改为fulfilled，失败时调用reject把状态改为rejected；三是一旦状态改变就不可逆，既不能从成功变失败，也不能从失败变成功，更不可能从成功再变成功。

放在RN原生通信里理解就很简单：原生方法的参数里如果有一个Promise对象，就意味着JS端的方法可用async/await来接收结果。promise.resolve(data)对应await的返回值，promise.reject(code, message)对应catch到的异常。

3.2 Android端Promise实现

java复制@ReactMethod
public void connectDevice(String deviceId, Promise promise) {
    try {
        Device device = connect(deviceId);
        WritableMap result = Arguments.createMap();
        result.putString("deviceId", device.getId());
        result.putString("status", "connected");
        promise.resolve(result);
    } catch (ConnectException e) {
        promise.reject("CONNECT_FAILED", e.getMessage());
    }
}

Android端的Promise是com.facebook.react.bridge.Promise接口，有resolve和reject两个方法。reject有三个重载：reject(String code, String message)、reject(String code, String message, Throwable throwable)、reject(String code, String message, Throwable throwable, WritableMap userInfo)。日常开发用前两个就够，throwable不为空时，错误信息里会带出原生堆栈，排查问题会省不少时间。

有一个体验优化的细节：promise.reject的code和message，JS端都能通过error.code、error.message拿到。我建议把code设计成稳定的字符串常量，比如"DEVICE_NOT_FOUND"、"TIMEOUT"、"AUTH_FAILED"，这样JS端就能针对不同的code做不同的提示和重试策略，而不是全凭message文本去猜。

3.3 iOS端Promise实现

iOS端Promise方式用的是RCTPromiseResolveBlock和RCTPromiseRejectBlock：

objc复制RCT_EXPORT_METHOD(connectDevice:(NSString *)deviceId
                  resolve:(RCTPromiseResolveBlock)resolve
                  reject:(RCTPromiseRejectBlock)reject)
{
  NSError *error = nil;
  Device *device = [self connectDevice:deviceId error:&error];
  if (error) {
    reject(@"CONNECT_FAILED", error.localizedDescription, error);
  } else {
    resolve(@{
      @"deviceId": device.deviceId,
      @"status": @"connected"
    });
  }
}

注意iOS端的resolve可以直接传入NSDictionary、NSString、NSNumber等类型，不需要像Android那样转换成WritableMap。RN框架会自动把兼容类型序列化并传递给JS。相比之下，iOS端的实现看起来会更简洁一些。

这里有个不少iOS开发容易忽略的点：RCTPromiseRejectBlock必须提供一个NSError作为第三个参数，哪怕你手头没有现成的error对象，也得构造一个[NSError errorWithDomain:...]传进去，否则编译不过。如果你确实不关心原生错误对象，传一个空的NSError也行，JS端拿到的error.userInfo可能没太多信息，但message是有效的。

3.4 JS端async/await配合Promise

Promise方式最大的优势，就是JS端能写成同步代码的样子：

js复制async function connectAndPrint(deviceId) {
  try {
    const result = await NativeModules.PrinterModule.connectDevice(deviceId);
    console.log('连接成功：', result.status);
    const printResult = await NativeModules.PrinterModule.print('hello');
    console.log('打印完成：', printResult.taskId);
  } catch (error) {
    // error.code / error.message 这里都能拿到
    if (error.code === 'CONNECT_FAILED') {
      Alert.alert('连接失败', error.message);
    }
  }
}

连续多个依赖原生结果的操作，用await一次排开，代码可读性比嵌套Callback强太多了。而且Promise天然支持Promise.all、Promise.race这些组合操作。比如App启动时既要从原生拿设备状态，又要在JS层拉业务配置，两个步骤互不依赖，完全可以用Promise.all并发等待，缩短启动耗时。这正好也是解决“react native 启动白屏”问题的一个小思路——把启动时的串行请求改成并发。

JS端的Promise还有一个特性：如果await一个被reject的Promise，没有用try...catch包裹，就会出现“Uncaught (in promise) ...”的报错。这在RN开发里经常见到，尤其是在原生模块的Promise没有默认兜底时。写业务代码的人很容易只写了成功路径，忘了catch，一旦原生端把某类边界情况reject了，前端直接崩在控制台里，用户端表现为页面没反应或者跳到错误边界。

3.5 Promise的边界与使用禁忌

Promise也有限制。最典型的一个是：Promise本质上只适合“一次性结果”的场景。你发起了一个异步操作，最终只会成功或者失败，没有第三种状态。如果你需要原生层持续上报进度，比如打印机的任务进度从10%到100%，Promise是表达不了的，因为你不能resolve多次，也不能中途往Promise里塞中间状态。这种场景应该用DeviceEventEmitter发送事件流，原生每次进度变化都emit一个事件，JS端订阅。

另一个禁忌是：原生端的Promise一旦resolve或reject，也同样是一次性的。有些代码在循环里调用同一个Promise的resolve，第一次生效，后面全部被忽略，而且不会有任何报错。排查起来会很困惑，因为逻辑上好像每一步都该执行，但实际只有第一步生效。原生端如果要防这个问题，同样得加执行标记。

4. Callback还是Promise：选型要分场景

4.1 两种方式的核心差异对比

我自己在项目里的选型依据，可以整理成一张表：

从表格里能看出来，Promise在大多数“调一次、等结果”的业务场景里都是更优解。我现在的习惯是：新写的原生方法，只要逻辑是一次性的，一律用Promise；只有那些历史SDK实在改不动、或者需要保持和老模块一致风格的时候，才继续用Callback。

4.2 多回调、事件流场景的变通做法

有一种业务场景容易让人犹豫：不是“一次性结果”，而是原生层在一个较长流程中多次回调JS。比如OTA固件升级，先回传“设备发现成功”，再回传“下载中，进度xx%”，最后回传“升级成功”或“升级失败”。这种用Callback和Promise都不合适。

这里我有一个推荐的模式：原生层暴露的方法本身用Promise，结果只表示“升级任务已成功启动”；后续的中间事件用事件流通道发送，JS端订阅事件流来更新UI。这样两者各司其职：启动结果是一次性的，用Promise收尾很干净；进度条是持续性的，交给事件流。

Android端发送事件用ReactContext.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class).emit(eventName, params)，iOS端用RCTEventEmitter或者直接通过bridge eventDispatcher。代码上都不复杂，但作用域划分明确之后，业务层写起来非常舒服。

4.3 事件机制、Callback、Promise的完整取舍

这三者放到一张图里理解会更快：

• Promise适合“一锤子买卖”，结果只出现一次，要么成功要么失败。
• Callback适合“简单反向通知”，可以设计成success/error双回调，但仍然是一次性。
• 事件流适合“持续或多次通知”，数据可以多次发送，JS端随时订阅、随时取消。

选择时先问自己一个问题：原生层到底要给JS层发送多少次结果？一次，就在Callback和Promise里选；多次，直接事件流。我问完自己这个问题，再没有在选型上纠结过。

如果你接手的是老项目，里面Callback和Promise混用，也不要急着推倒重来。可以在封装的这一层做统一：底层暴露的可能是Callback形式，但业务层封装一个Promise外壳，内部适配。这样上层业务代码风格统一，底层长期里再逐步替换。

5. 常见问题与排查技巧实录

5.1 回调没触发，JS界面卡住不动

遇到回调完全不触发的情况，优先查三件事。第一，原生方法有没有被正确导出，检查@ReactMethod注解或RCT_EXPORT_METHOD宏是否遗漏。第二，原生方法是不是因为参数类型不匹配，在Bridge阶段就被打回了。我遇到过Callback不小心被写在参数列表的第几个位置，JS端传参顺序和原生端定义不一致，结果回调一直没进来。第三，原生端有没有真正执行到invoke或resolve，在原生代码里打日志确认。

曾经有个项目，Android端回调没触发的原因是模块还没完成初始化，方法调用被Bridge接收但模块管理器的hasModule返回false，直接丢弃了。这个问题在App冷启动后会偶现，和“react native 启动白屏”的现象经常同时出现。后来我们在JS端加了重试机制，等AppRegistry完全就绪后再调用原生方法，白屏概率大幅下降。

5.2 Uncaught (in promise) SyntaxError 的根源

这个报错在RN开发里非常高发，字面意思是Promise被reject了但没人处理，而且reject的内容是一个JSON解析失败后的异常对象。常见于原生端返回的字符串不是合法的JSON，但JS端用了JSON.parse去解析。比如原生端返回了一个普通的错误文本，JS端在catch分支里又对error.message做JSON.parse，那就会二次抛出“not valid JSON”。

我的建议是：在原生端就保证返回的数据结构稳定，能返回WritableMap就不要返回JSON字符串。如果确实只能返回字符串，JS端在做JSON.parse之前先判断字符串首尾是不是{或[，并且在catch分支里不要再做任何解析操作。类似的坑也常见于从原生文件读取内容、从服务端轮询拿状态这些场景。

5.3 Callback重复调用导致业务执行两次

Callback设计成一次性的，但原生端代码没有守卫时，很容易出现“既走成功又走失败”的重复调用。最典型的是在AsyncTask的回调里调了successCallback，又在finally块里因为某个状态判断再次调用了successCallback。

排查时先在原生端加统一的出口日志，每次invoke都打印一个堆栈标识。真的出现重复调用，就在方法内部加布尔标记。顺便说一句，Promise在这方面比Callback有天然优势，框架层面就会禁止二次resolve/reject，虽然也不会报错，但第二次调用是静默无效的，相比Callback的“每次都会生效”要安全得多。

5.4 原生线程问题引发的崩溃和状态丢失

Android端原生方法默认执行在NativeModules线程，这个线程不是主线程。你在scanDevices里做完扫描后直接successCallback.invoke(data)，如果后续处理里有UI操作，从原生的角度看不到问题，但从JS端角度，回调触发后如果接着做setState或者导航，有一定概率出现界面更新不稳定的情况。

更危险的是，如果你在原生回调里调用了某些必须跑在主线程的SDK方法，比如蓝牙某些版本的startLeScan，线程不对直接就崩。我的做法是，凡是涉及需要主线程才能工作的原生代码，在方法内部用runOnUiThread包一层；回调invoke本身放在任务完成之后，确保数据都准备好了再触发，不要在一个子线程里又调用另一个子线程的任务，时序会很难控制。

5.5 新架构（TurboModule）下的回调变化

RN 0.70之后新架构全面铺开，TurboModule替代了老式Bridge，这里有一个很多人没注意到的变化：TurboModule下的原生模块方法，JS端调用时参数类型检查更严格了，某些旧代码里“JS传一个对象，原生端用ReadableMap接收”的宽松写法，在新架构下可能出问题。

Callback和Promise本身在新架构里依然是官方支持的，原理也基本一致。但从老架构迁移到新架构时，建议把原生模块的代码整体过一遍，重点检查三点：getName是否正常返回、参数类型是否严格匹配、异步回调是否在新架构的帧调度时机下触发了异常。我迁移过一个老SDK，遇到的最大坑是原生模块初始化时机变了，导致App启动初期调用原生方法返回null。最终是在自有封装层加了一个模块是否就绪的判断，再配合重试，才彻底稳定。

5.6 启动白屏与原生模块初始化的关联

“react native 启动白屏”本质上不是回调机制的问题，但它和回调有个隐蔽的关联：很多页面在启动后立刻调用原生方法，而原生模块可能还在初始化中。如果调用结果通过Promise返回，JS端没有catch到这个“模块未就绪”的reject，页面数据一直为空，渲染出来的就是白屏。

这种问题排查时不要光看JS端逻辑，先在原生模块的initialize生命周期里加日志，确认模块就绪的时机。然后在JS端的启动流程里增加一个统一的ensureNativeModuleReady钩子，模块就绪后再发起真正的业务调用。这一步做扎实，白屏概率能压到一个很低的水平，也能避免很多“回调没触发”的误判。

6. 最后分享一点实战经验

我个人的体会是，Callback和Promise没有绝对的好坏，关键是把适用范围划清楚。内部业务模块我基本全用Promise，因为上游的开发者用async/await写业务逻辑非常顺手，错误处理也统一。只有对接第三方SDK时，如果SDK本身就是回调风格，我才会在原生适配层保留Callback，然后再封装一层Promise暴露给JS。这样最底层的形态贴近SDK，上层体验又统一。

调试这类跨端调用，我的习惯是给每个原生方法的关键路径都打上可过滤的日志，用统一的tag或前缀区分。真的出了问题，先看原生日志确认方法有没有被调到、有没有走到invoke或resolve，再看JS端日志确认回调有没有被正确接收。只要这“一进一出”对得上，剩下的基本都是业务逻辑的问题。这套排查方法帮我省了太多次在两头反复切换调试的时间。