React Native + Expo + Metro + 原生实现完全解析

flowchart LR
  subgraph OLD["旧架构（Bridge）"]
    direction TB
    J1["JS 线程<br/>React 逻辑"] -->|"JSON 序列化"| BR["Bridge<br/>异步队列 ⚠"]
    BR -->|"JSON 反序列化"| N1["原生线程<br/>UIKit / Android View"]
    SH["Shadow 线程<br/>Yoga 布局"] --> N1
  end
  subgraph NEW["新架构（JSI）"]
    direction TB
    HM["Hermes 引擎<br/>字节码执行"] -->|"直接 C++ 引用"| JSI["JSI<br/>Host Objects"]
    JSI --> FAB["Fabric<br/>同步渲染器"]
    JSI --> TM["TurboModules<br/>懒加载初始化"]
    FAB --> N2["原生层"]
    TM --> N2
  end

flowchart TD
  SPEC["JS Spec 文件<br/>用 TypeScript / Flow 定义类型"]

  subgraph BUILD["构建时"]
    CG["Codegen<br/>在 pod install / Gradle 时执行"]
  end

  subgraph OUT["生成的产物"]
    CPP["C++ 抽象类<br/>TurboModule 基础接口"]
    DESC["Component Descriptor<br/>用于 Fabric 原生组件"]
    JSTYPE["JS 类型定义<br/>等同于 .d.ts"]
  end

  subgraph NATIVE["原生实现"]
    IOS["iOS<br/>使用 Swift / Obj-C 实现"]
    AND["Android<br/>使用 Kotlin / Java 实现"]
  end

  RUNTIME["通过 JSI<br/>类型安全、同步调用"]

  SPEC --> CG
  CG --> CPP & DESC & JSTYPE
  CPP --> IOS & AND
  DESC --> IOS & AND
  IOS --> RUNTIME
  AND --> RUNTIME

flowchart LR
  SRC[".js / .ts / .tsx<br/>源文件"]
  RES["解析<br/>import 路径解析"]
  TRA["转换<br/>Babel ES 转换"]
  SER["序列化<br/>生成 Bundle"]
  DEV["发送到设备<br/>HTTP :8081"]
  HMR["HMR<br/>仅重发变更模块"]
  CACHE["文件系统缓存<br/>第二次起速度更快"]

  SRC --> RES --> TRA --> SER --> DEV
  TRA -.->|"检测文件变更"| HMR
  HMR -.->|"保留状态实时反映"| DEV
  TRA <-.->|"缓存转换结果"| CACHE

flowchart TD
  APP["你的应用<br/>App.tsx / screens / hooks"]
  SDK["Expo SDK<br/>expo-camera / expo-location / expo-router …"]
  EMC["expo-modules-core<br/>Swift / Kotlin DSL 类型安全描述"]
  RN["React Native Core<br/>View / Text / Animated / StyleSheet"]
  IOS["iOS<br/>UIKit / AVFoundation / CoreLocation"]
  AND["Android<br/>View / Camera2 / LocationManager"]
  GO["Expo Go<br/>扫描二维码即可启动"]
  EASB["EAS Build<br/>在云端生成 .ipa / .apk"]
  EASU["EAS Update<br/>通过 OTA 仅发布 JS Bundle"]
  STORE["App Store / Google Play"]

  APP --> SDK
  EMC --> SDK
  SDK --> RN
  RN --> IOS & AND
  GO -->|"开发时托管"| APP
  EASB --> STORE
  EASU -->|"无需 App Store 审核"| APP

flowchart TD
  START["需要什么原生功能？"]

  START --> Q1{"Expo SDK / 公开库<br/>能否覆盖？"}
  Q1 -->|"是"| MANAGED["Managed Workflow<br/>无需原生代码<br/>只需 npx expo start"]
  Q1 -->|"否"| Q2{"只需配置变更？<br/>(Info.plist / AndroidManifest 追加等)"}
  Q2 -->|"是"| PLUGIN["创建 Config Plugin<br/>追加到 app.json<br/>prebuild 自动应用"]
  Q2 -->|"否"| Q3{"自定义原生代码的规模？"}
  Q3 -->|"轻量<br/>（封装现有 SDK）"| BARE["Bare Workflow<br/>npx expo prebuild<br/>→ 直接管理 ios/ android/"]
  Q3 -->|"大规模<br/>（自定义模块 / UI）"| MODULE{"构建什么？"}
  MODULE -->|"逻辑类<br/>蓝牙 / 支付 / 加密"| TM["TurboModule<br/>+ Codegen"]
  MODULE -->|"UI 组件类<br/>自定义相机视图等"| FAB["Fabric Component<br/>+ Codegen"]
  BARE --> TM & FAB
  PLUGIN --> BARE

flowchart TB
  subgraph JS["JS 层（Hermes）"]
    APP["应用代码 / React 组件"]
    SPEC["JS Spec<br/>（TypeScript + TurboModuleRegistry）"]
  end

  subgraph CODEGEN["Codegen（构建时自动生成）"]
    GEN_CPP["C++ 抽象类<br/>TurboModule / ComponentDescriptor"]
    GEN_SHADOW["ShadowNode / Props 定义"]
  end

  subgraph JSI_LAYER["JSI 层（C++）"]
    JSI["JSI Host Object"]
    FABRIC["Fabric 渲染器"]
  end

  subgraph NATIVE_IOS["iOS 原生实现"]
    SWIFT["Swift / Obj-C 实现类<br/>（继承 C++ 抽象类）"]
    SDK_IOS["内部 SDK / 外部 .framework<br/>如 CoreBluetooth / Stripe"]
    UIVIEW["UIView 子类<br/>（自定义 UI 组件）"]
  end

  subgraph NATIVE_AND["Android 原生实现"]
    KOTLIN["Kotlin / Java 实现类<br/>（继承 C++ 抽象类）"]
    SDK_AND["内部 SDK / 外部 .aar<br/>如 BluetoothGatt / Stripe"]
    ANDROIDVIEW["View 子类<br/>（自定义 UI 组件）"]
  end

  SPEC -->|"读取类型定义"| CODEGEN
  GEN_CPP --> JSI
  GEN_SHADOW --> FABRIC
  APP -->|"同步 / 异步调用"| JSI
  JSI --> SWIFT & KOTLIN
  FABRIC --> UIVIEW & ANDROIDVIEW
  SWIFT --> SDK_IOS
  KOTLIN --> SDK_AND

// src/specs/NativeBluetoothModule.ts
import type { TurboModule, CodegenTypes } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export type ScanResult = {
  id: string;
  name: string;
  rssi: number;
};

export interface Spec extends TurboModule {
  startScan(serviceUUIDs: string[]): void;
  stopScan(): void;
  connect(deviceId: string): Promise<boolean>;
  readonly onDeviceFound: CodegenTypes.EventEmitter<ScanResult>;
}

export default TurboModuleRegistry.getEnforcing<Spec>('NativeBluetoothModule');

flowchart LR
  SPEC["NativeBluetoothModule.ts<br/>（开发者编写）"]

  subgraph AUTO["自动生成的代码"]
    CPP["C++ glue code<br/>JSI / Codegen 生成物"]
    IOS_H["iOS glue code<br/>Obj-C++ / header 生成物"]
    AND_J["Android glue code<br/>JNI / Spec 类生成物"]
  end

  subgraph IMPL["开发者实现"]
    SWIFT_IMPL["NativeBluetoothModule.swift<br/>实现生成的 Spec，调用 CoreBluetooth"]
    KOTLIN_IMPL["NativeBluetoothModule.kt<br/>实现生成的 Spec，调用 BluetoothGatt"]
  end

  SPEC --> CPP
  SPEC --> IOS_H
  SPEC --> AND_J
  CPP --> SWIFT_IMPL & KOTLIN_IMPL
  IOS_H --> SWIFT_IMPL
  AND_J --> KOTLIN_IMPL

// ios/NativeBluetoothModule.swift
import CoreBluetooth

@objc(NativeBluetoothModule)
class NativeBluetoothModule: NativeBluetoothModuleSpec, CBCentralManagerDelegate {
  private var centralManager: CBCentralManager!

  override func startScan(_ serviceUUIDs: [String]) {
    let uuids = serviceUUIDs.map { CBUUID(string: $0) }
    centralManager.scanForPeripherals(withServices: uuids)
  }

  func centralManager(_ central: CBCentralManager,
                      didDiscover peripheral: CBPeripheral,
                      advertisementData: [String: Any], rssi: NSNumber) {
    emitOnDeviceFound([
      "id": peripheral.identifier.uuidString,
      "name": peripheral.name ?? "",
      "rssi": rssi
    ])
  }
}

// android/src/main/java/NativeBluetoothModule.kt
class NativeBluetoothModule(reactContext: ReactApplicationContext)
    : NativeBluetoothModuleSpec(reactContext), BluetoothGatt.Callback {

  private val adapter = BluetoothAdapter.getDefaultAdapter()

  override fun startScan(serviceUUIDs: ReadableArray) {
    val filters = serviceUUIDs.toArrayList().map { uuid ->
      ScanFilter.Builder().setServiceUuid(ParcelUuid.fromString(uuid as String)).build()
    }
    adapter.bluetoothLeScanner.startScan(filters, ScanSettings.Builder().build(), scanCallback)
  }

  private val scanCallback = object : ScanCallback() {
    override fun onScanResult(callbackType: Int, result: ScanResult) {
      val params = Arguments.createMap().apply {
        putString("id", result.device.address)
        putString("name", result.device.name ?: "")
        putInt("rssi", result.rssi)
      }
      emitOnDeviceFound(params)
    }
  }
}

// src/specs/NativeCameraViewSpec.ts
import type { ViewProps } from 'react-native';
import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
import type { DirectEventHandler, Float } from 'react-native/Libraries/Types/CodegenTypes';

type FrameCapturedEvent = Readonly<{
  uri: string;
}>;

interface NativeProps extends ViewProps {
  zoom?: Float;          // Codegen 将 Float 转换为 CGFloat / float
  torchEnabled?: boolean;
  onFrameCaptured?: DirectEventHandler<FrameCapturedEvent>;
}

export default codegenNativeComponent<NativeProps>('CameraView');

# ios/Podfile
pod 'CompanyPaymentSDK', :path => '../vendor/ios/CompanyPaymentSDK'
# 或 xcframework 的情况
pod 'CompanyPaymentSDK', :podspec => '../vendor/ios/CompanyPaymentSDK.podspec'

// android/app/build.gradle
dependencies {
  implementation files('../vendor/android/company-payment-sdk.aar')
  // 或内部 Maven 仓库
  implementation 'com.company:payment-sdk:1.4.0'
}

flowchart TD
  INIT["npx create-expo-app MyApp<br/>--template blank-typescript"]

  subgraph START["npx expo start"]
    METRO["Metro Bundler 启动<br/>port 8081"]
    QR["显示二维码 + 快捷键<br/>i = iOS  a = Android  w = Web"]
  end

  subgraph DEVICE["选择目标设备"]
    SIM["iOS Simulator<br/>Xcode 自带（仅 Mac）"]
    EMU["Android Emulator<br/>Android Studio AVD"]
    GO["真机 + Expo Go<br/>局域网或 Tunnel"]
  end

  subgraph NATIVE_BUILD["仅首次：原生构建"]
    POD["pod install<br/>iOS CocoaPods"]
    GRADLE["Gradle build<br/>Android"]
    CODEGEN_RUN["Codegen 执行<br/>Spec → 原生模板"]
  end

  BUNDLE["JS Bundle 传输到设备<br/>通过 Metro HTTP 服务器"]
  RENDER["画面显示"]

  INIT --> START
  METRO --> QR
  QR --> SIM & EMU & GO
  SIM --> NATIVE_BUILD
  EMU --> NATIVE_BUILD
  NATIVE_BUILD --> BUNDLE
  GO --> BUNDLE
  BUNDLE --> RENDER

flowchart TD
  subgraph CHANGE["按变更类型分支"]
    JS_ONLY["仅 JS 变更<br/>组件 / 逻辑 / 样式"]
    NATIVE_CHANGE["原生代码变更<br/>Swift / Kotlin / Spec / Podfile"]
  end

  subgraph JS_LOOP["JS 变更循环（快速）"]
    METRO_HMR["Metro HMR<br/>传输差异 Bundle<br/>数百毫秒"]
    SIM_JS["模拟器即时反映<br/>保留应用状态"]
  end

  subgraph NATIVE_LOOP["原生变更循环（慢）"]
    CODEGEN_RUN["重新执行 Codegen<br/>pod install (iOS)<br/>Gradle sync (Android)"]
    REBUILD["原生重新构建<br/>npx expo run:ios<br/>npx expo run:android"]
    SIM_NATIVE["在模拟器 / 真机上确认"]
  end

  JS_ONLY --> METRO_HMR --> SIM_JS
  NATIVE_CHANGE --> CODEGEN_RUN --> REBUILD --> SIM_NATIVE

  SIM_JS -->|"没有问题"| DONE["验证完成"]
  SIM_NATIVE -->|"没有问题"| DONE
  SIM_JS -->|"发现 Bug"| DEBUG_JS["Hermes Debugger<br/>React DevTools"]
  SIM_NATIVE -->|"原生崩溃"| DEBUG_NATIVE["Xcode / Android Studio<br/>原生调试器"]
  DEBUG_JS --> JS_ONLY
  DEBUG_NATIVE --> NATIVE_CHANGE

flowchart TD
  SYMPTOM["观察症状"]

  SYMPTOM --> Q1{"崩溃类型"}

  Q1 -->|"JS 错误<br/>LogBox 红屏"| JS_ERR["用 Hermes Debugger 调查<br/>断点、堆栈跟踪<br/>Source Map 显示 TS 行号"]
  Q1 -->|"原生崩溃<br/>应用崩溃 / 冻结"| NAT_ERR["检查崩溃日志"]
  Q1 -->|"能运行但<br/>结果不正确"| BORDER["怀疑 JS↔Native 边界"]

  NAT_ERR --> IOS_CRASH["iOS: Xcode<br/>Debug Navigator<br/>+ lldb 附加"]
  NAT_ERR --> AND_CRASH["Android: Android Studio<br/>Logcat 堆栈跟踪<br/>+ Native Debugger"]

  BORDER --> LOG_IOS["iOS: NSLog / os_log<br/>npx react-native log-ios"]
  BORDER --> LOG_AND["Android: Log.d<br/>npx react-native log-android"]
  BORDER --> JS_LOG["JS 侧: console.log<br/>确认 TurboModule 返回值"]

  IOS_CRASH --> INSTRUMENTS["Instruments<br/>Time Profiler / Allocations<br/>定位内存泄漏 / CPU"]
  AND_CRASH --> PROFILER["Android Studio<br/>Memory / CPU Profiler"]

  JS_ERR --> FIXED["修复 → Metro HMR 即时反映"]
  INSTRUMENTS --> FIXED2["修复 → npx expo run:ios 确认"]
  PROFILER --> FIXED3["修复 → npx expo run:android 确认"]
  LOG_IOS & LOG_AND & JS_LOG --> BORDER2["定位根本原因<br/>→ 修复 Spec / 实现"]

# iOS: 将 lldb 附加到运行中的模拟器
npx expo run:ios --configuration Debug
# → Xcode 自动打开并附加调试器

# Android
npx expo run:android
# → "Run > Attach Debugger to Android Process" 附加

// Swift 侧
os_log("BluetoothModule.connect called: %{public}@", deviceId)
// → 用 npx react-native log-ios 过滤查看

// Kotlin 侧
Log.d("BluetoothModule", "connect called: $deviceId")
// → 用 npx react-native log-android 过滤查看

// JS 侧
const result = await BluetoothModule.connect(deviceId);
console.log('connect result:', result); // 输出到 Metro

npx react-devtools
# → 在端口 8097 等待设备连接

① 编写 JS Spec（TypeScript 类型定义）
       ↓
② pod install / gradle build → Codegen 自动生成 C++ 模板
       ↓
③ 用 Swift / Kotlin 实现（调用内部 SDK / 外部库）
       ↓
④ npx expo run:ios / run:android 原生构建 & 模拟器验证
       ↓
⑤ 编写 JS 调用代码 → 通过 Metro HMR 快速迭代
       ↓
⑥ JS 错误 → Hermes Debugger
   原生崩溃 → Xcode / Android Studio 调试器
   边界不一致 → 用 log-ios / log-android + console.log 夹击
       ↓
⑦ 在真机上验证蓝牙 / 相机 / 传感器等功能
       ↓
⑧ EAS Build 生成应用商店发布的二进制文件