Turbo

React Native 基于 JSI (TurboModules) 高性能原生 API 封装指南

在 React Native(RN)新架构中,基于 JSI (JavaScript Interface) 的 TurboModules 配合自动化的 Swift/Kotlin 封装,是高效调用原生 API 的终极方案。

传统架构(Bridge)采用 JSON 异步序列化通信,存在性能损耗与异步阻塞;而基于 JSI 的新架构支持 JS 与 Native 的直接 C++ 内存映射,实现了同步/高性能调用、强类型安全以及零序列化开销。


一、 整体设计架构与核心原则

┌─────────────────────────────────────────────────────────────┐
│                      JavaScript 层                         │
│   JavaScript 接口 (Spec) + 类型导出 + 优雅的错误处理/降级      │
└──────────────────────────────┬──────────────────────────────┘
                               │
                TurboModule Spec (C++ 胶水代码自动生成)
                               │
┌──────────────────────────────▼──────────────────────────────┐
│                       Native 接口层                          │
│   iOS: Objective-C++ (或 Swift 桥接)  │  Android: Kotlin/JNI│
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────┐
│                    系统原生底层 API                          │
│   iOS: AVFoundation / CoreLocation / HealthKit 等           │
│   Android: CameraX / LocationServices 等                    │
└─────────────────────────────────────────────────────────────┘

核心设计原则

  • 规范先行:定义清晰的 Spec 规范,由 Codegen 自动编译出高性能的 C++ 桥接头文件。
  • 轻量桥接,逻辑下沉:Native 封装类只做协议翻译与逻辑路由,具体业务/底层能力独立解耦为 Native Service。
  • 线程模型分离:
  • 涉及 UI / 系统权限的 API 显式调度至主线程(Main Thread)。
  • 耗时计算、密集 I/O 或高频传感器数据调度至后台专用队列(Custom Dispatch Queue / Coroutine Scope)。
  • 统一数据结构:复杂数据传递优先采用 ArrayBuffer(针对二进制/图片/字节流)或纯基本类型,避免大对象在 Bridge/JSI 间反复解构。

二、 具体实现步骤(以 Swift + Kotlin + JS 为例)

假设我们需要封装一个高频/高性能获取系统设备状态(如高精度的内存/电池/传感器数据)的原生模块 NativeDeviceInfo。

Step 1: 定义 JavaScript Spec 规范

在 JS 端新建文件 NativeDeviceInfo.js(必须遵循 RN Codegen 的命名约束):

import { TurboModuleRegistry } from 'react-native';

// 从 TurboModule 注册表中获取原生模块对象
// 字符串参数 'NativeDeviceInfo' 必须与 Native 端注册的名称完全一致
const NativeDeviceInfo = TurboModuleRegistry.getEnforcing('NativeDeviceInfo');

export default NativeDeviceInfo;


Step 2: iOS 端的实现 (Swift + Objective-C++)

iOS 的 TurboModule 需要用 Objective-C++ (.mm) 暴露接口,再调用高效的 Swift 实现类。

1. Swift 业务服务类 (DeviceInfoService.swift)

import Foundation
import UIKit

@objc(DeviceInfoService)
public class DeviceInfoService: NSObject {
    
    // 专用的后台队列,避免阻塞主线程
    private let queue = DispatchQueue(label: "com.app.deviceinfo", qos: .userInitiated)

    // 1. 同步 API
    @objc public func getMemoryUsage() -> Double {
        var info = mach_task_basic_info()
        var count = mach_msg_type_number_t(MemoryLayout<mach_task_basic_info>.size) / 4
        let kerr: kern_return_t = withUnsafeMutablePointer(to: &info) {
            $0.withMemoryRebound(to: integer_t.self, capacity: Int(count)) {
                task_info(mach_task_self_, task_flavor_t(MACH_TASK_BASIC_INFO), $0, &count)
            }
        }
        return kerr == KERN_SUCCESS ? Double(info.resident_size) : 0.0
    }

    // 2. 异步 API
    @objc public func getBatteryStatus(
        resolve: @escaping RCTPromiseResolveBlock,
        reject: @escaping RCTPromiseRejectBlock
    ) {
        queue.async {
            UIDevice.current.isBatteryMonitoringEnabled = true
            let level = UIDevice.current.batteryLevel
            let isCharging = UIDevice.current.batteryState == .charging || UIDevice.current.batteryState == .full
            
            let result: [String: Any] = [
                "level": level,
                "isCharging": isCharging
            ]
            resolve(result)
        }
    }
}

2. 模块注册与桥接 (NativeDeviceInfo.mm)

#import <React/RCTBridgeModule.h>
#import <React/RCTUtils.h>
#import "your_project_name-Swift.h" // 引入你的 Swift 编译头文件

@interface NativeDeviceInfo : NSObject <RCTBridgeModule>
@property (nonatomic, strong) DeviceInfoService *service;
@end

@implementation NativeDeviceInfo

// 导出模块名供 JS 的 TurboModuleRegistry 调用
RCT_EXPORT_MODULE(NativeDeviceInfo)

- (instancetype)init {
    if (self = [super init]) {
        _service = [[DeviceInfoService alloc] init];
    }
    return self;
}

// 设置 Native 执行队列,避免阻塞主线程
- (dispatch_queue_t)methodQueue {
    return dispatch_queue_create("com.app.nativedeviceinfo.queue", DISPATCH_QUEUE_SERIAL);
}

// 1. 导出 JSI 同步方法
RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getMemoryUsageSync) {
    double memory = [self.service getMemoryUsage];
    return @(memory);
}

// 2. 导出异步 Promise 方法
RCT_EXPORT_METHOD(getBatteryStatus:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject) {
    [self.service getBatteryStatusWithResolve:resolve reject:reject];
}

// 3. 普通无返回值方法
RCT_EXPORT_METHOD(clearNativeCache) {
    // 缓存清理逻辑...
}

@end


Step 3: Android 端的实现 (Kotlin)

在 Android 端,继承 ReactContextBaseJavaModule 配合协程(Coroutines)实现高性能并发操作:

package com.yourapp.modules

import com.facebook.react.bridge.Promise
import com.facebook.react.bridge.Arguments
import com.facebook.react.bridge.ReactApplicationContext
import com.facebook.react.bridge.ReactContextBaseJavaModule
import com.facebook.react.bridge.ReactMethod
import com.facebook.react.module.annotations.ReactModule
import kotlinx.coroutines.*

@ReactModule(name = NativeDeviceInfoModule.NAME)
class NativeDeviceInfoModule(reactContext: ReactApplicationContext) :
    ReactContextBaseJavaModule(reactContext) {

    private val moduleScope = CoroutineScope(Dispatchers.IO + SupervisorJob())

    companion object {
        const val NAME = "NativeDeviceInfo"
    }

    override fun getName(): String = NAME

    // 1. 同步 JSI 方法 (@ReactMethod(isBlockingSynchronousMethod = true))
    @ReactMethod(isBlockingSynchronousMethod = true)
    fun getMemoryUsageSync(): Double {
        val runtime = Runtime.getRuntime()
        val usedMemory = runtime.totalMemory() - runtime.freeMemory()
        return usedMemory.toDouble()
    }

    // 2. 异步 Promise 方法 (使用 Kotlin 协程后台处理)
    @ReactMethod
    fun getBatteryStatus(promise: Promise) {
        moduleScope.launch {
            try {
                val batteryLevel = 0.85 
                val isCharging = true

                val resultMap = Arguments.createMap().apply {
                    putDouble("level", batteryLevel)
                    putBoolean("isCharging", isCharging)
                }
                
                promise.resolve(resultMap)
            } catch (e: Exception) {
                promise.reject("ERR_BATTERY", e.message, e)
            }
        }
    }

    @ReactMethod
    fun clearNativeCache() {
        moduleScope.launch {
            // 清理缓存...
        }
    }

    override fun onCatalystInstanceDestroy() {
        super.onCatalystInstanceDestroy()
        moduleScope.cancel() // 防止内存泄漏
    }
}


Step 4: JS 层的二次封装与使用 (DeviceInfoManager.js)

原生暴露的模块应当经过 JS 层的防御性封装,统一错误拦截、格式化与兜底方案:

import NativeDeviceInfo from './NativeDeviceInfo';

export class DeviceInfoManager {
  /**
   * 同步获取内存使用量(字节)
   * @returns {number} 内存字节数,失败返回 -1
   */
  static getMemoryUsage() {
    try {
      if (NativeDeviceInfo && typeof NativeDeviceInfo.getMemoryUsageSync === 'function') {
        return NativeDeviceInfo.getMemoryUsageSync();
      }
      return -1;
    } catch (e) {
      console.warn('[DeviceInfoManager] 同步获取内存失败:', e);
      return -1; // 降级兜底
    }
  }

  /**
   * 异步获取当前电池状态
   * @returns {Promise<{level: number, isCharging: boolean, levelFormatted: string}>}
   */
  static async getBatteryStatus() {
    try {
      const status = await NativeDeviceInfo.getBatteryStatus();
      return {
        ...status,
        levelFormatted: `${Math.round((status?.level || 0) * 100)}%`,
      };
    } catch (e) {
      console.error('[DeviceInfoManager] 获取电池状态失败:', e);
      throw e;
    }
  }

  /**
   * 清除原生缓存
   */
  static clearCache() {
    if (NativeDeviceInfo && typeof NativeDeviceInfo.clearNativeCache === 'function') {
      NativeDeviceInfo.clearNativeCache();
    }
  }
}


三、 极致性能调优的关键点(最佳实践)

  1. 避免高频数据传输时的对象序列化:
    如果涉及音视频流、图像像素、传感器点云等大批量数据,不要用 Array / Object 传递,建议使用 ArrayBuffer / TypedArray。JSI 允许 JS 和 Native 直接共享底层内存块(Zero-Copy),效率可提升数倍。
  2. 正确选择同步(Sync)与异步(Async):
  • 同步调用(...Sync()):仅适用于耗时极短(如 < 1ms)的属性获取(如计算内存、读取变量)。千万不要在同步方法里做磁盘 I/O、网络请求或复杂锁等待,否则会导致 JS 线程和 UI 直接卡顿。
  • 异步调用(Promise / Callback):所有耗时操作必须走异步,并在 Native 端显式派发到后台线程处理。
  1. 事件订阅机制(Native \rightarrow JS 高频推送):
    如果 Native 端有持续高频的数据更新(如 GPS 定位、陀螺仪数据),不要用轮询(Polling)方式调用 API,应该使用 EventEmitter 订阅机制:
  • iOS: RCTEventEmitter
  • Android: ReactContext.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
  1. 自动化构建工具选型:
    如果不希望手工处理大量的 ObjC++ / JNI 胶水代码,推荐使用第三方跨平台工具库 Nitro Modules(由 Marc Rousavy 开源)或 Expo Modules API,它们底层基于 C++ JSI 进行了二次极佳的封装,可以用纯 Swift/Kotlin 极其优雅地编写无缝 JSI 原生模块。

一只手:记作 1
最合适:记作 1.25

你学会找女朋友了吗。哈哈哈...

最后编辑于 :
©著作权归作者所有,转载或内容合作请联系作者
【社区内容提示】社区部分内容疑似由AI辅助生成,浏览时请结合常识与多方信息审慎甄别。
平台声明:文章内容(如有图片或视频亦包括在内)由作者上传并发布,文章内容仅代表作者本人观点,简书系信息发布平台,仅提供信息存储服务。

相关阅读更多精彩内容

友情链接更多精彩内容