集成 React Native 方案设计
说明：此文由《底座app集成 React Native 方案设计.docx》转换而来，为方便阅读转为md
一、方案背景与目标
1. 现状痛点
- 热更新缺失：底座 App 2.0 依赖原生版本迭代，Bug 修复和功能更新需通过应用商店审核，迭代周期长（通常 1-7 天），无法快速响应业务需求。
- 三端开发成本高：同一需求需在 iOS、Android 及鸿蒙（如鸿蒙或其他平台）分别开发，存在重复劳动，且维护成本随业务复杂度线性增长。
- 体验一致性差：因系统特性差异，三端实现逻辑和 UI 效果难以统一，导致用户体验割裂，测试验收成本高。
2. 核心目标
通过引入 React Native（以下简称 RN）框架，实现：
- 热更新能力：支持 JS 层代码动态更新，缩短迭代周期至小时级。
- 三端统一：一套业务代码覆盖多端，减少重复开发。
- 效率提升：降低跨端适配成本，统一开发规范和体验标准。
二、React Native 集成架构设计
1. 整体架构图（混合架构模式）
采用 “原生底座 + RN 模块” 的混合架构，原生层负责核心能力和基础体验，RN 层负责业务快速迭代，架构分层如下：
2. 架构核心说明
- 分层职责清晰：原生层聚焦稳定性和核心能力，RN 层聚焦业务灵活性，桥接层确保两者无缝通信。
- 渐进式集成：无需重构现有原生代码，通过新增 RN 模块逐步替换或补充业务，降低风险。
- 热更新支持：RN 业务代码打包为 JS Bundle，通过服务器动态下发，原生代码仍走应用商店更新（核心能力变更时）。
三、React Native 核心依赖与第三方库集成
选择成熟、社区活跃的库，确保稳定性和三端一致性，核心库清单如下
| 类别 | 推荐库 | 作用说明 |
|---|---|---|
| 基础框架 | react-native | RN 核心框架，提供跨端渲染能力 |
| 导航路由 | react-navigation / react-native-navigation | 统一三端导航逻辑（栈导航、标签页、抽屉），支持原生导航栏混合使用 |
| 状态管理 | redux-toolkit / mobx / recoil | 管理全局状态（如用户信息、购物车），确保三端状态同步 |
| UI 组件库 | Ant Design Mobile RN / Taro UI | 提供统一设计规范的组件（按钮、表单、列表等），减少跨端样式适配成本 |
| 网络请求 | axios / react-native-axios | 封装 HTTP 请求，统一处理拦截器（token 附加、错误统一处理） |
| 本地存储 | @react-native-async-storage/async-storage | 替代 localStorage，适配移动端持久化存储 |
| 设备交互 | react-native-device-info | 获取设备信息（型号、系统版本），用于适配或统计 |
| 图片处理 | react-native-fast-image | 优化图片加载（缓存、预加载），提升 RN 页面性能 |
| 桥接工具 | react-native-bridge（自定义） | 封装原生与 RN 交互接口（见下文 “交互接口设计”） |
集成原则：优先选择无原生依赖或轻量原生依赖的库，降低三端适配成本；核心库需经过稳定性测试，避免频繁更新导致兼容问题。
四、原生与 React Native 交互接口设计
为实现 “RN 与 App 完美结合”，需设计标准化的交互接口，覆盖数据传递、能力调用、事件通知三大场景。
1. 接口设计原则
- 单一职责：一个接口只处理一个核心功能（如 “获取用户 Token”“打开相机”）。
- 参数标准化：入参 / 出参统一使用 JSON 格式，明确字段类型和必填项（如{ code: 200, data: {}, msg: "" }）。
- 错误处理：统一错误码（如1001：权限不足，1002：参数错误），便于问题定位。
- 版本兼容：接口变更需预留兼容期，支持 “新接口 + 旧实现” 过渡。
2. 核心交互场景
（1）RN 调用原生能力（Method Call）
通过原生 Module 暴露接口，RN 通过NativeModules调用：
用户体系：
- getUserInfo()：获取当前登录用户信息（用户名、头像、权限）
- login(params)：调用原生登录页（支持手机号 / 第三方登录），返回登录结果
设备能力：
- openCamera(params)：调起原生相机，返回拍摄图片路径
- getLocation()：获取地理位置（依赖原生定位 SDK）
原生服务：
- pay(params)：调用原生支付 SDK（微信 / 支付宝），返回支付结果
- share(params)：调用原生分享（支持微信 / QQ）
（2）原生通知 RN 事件（Event Emit）
通过DeviceEventEmitter发送事件，RN 监听接收：
- 状态变更：
- onLoginStateChange：登录状态变化（登录 / 登出），传递最新用户信息
- onNetworkChange：网络状态切换（4G/WiFi/ 离线），触发 RN 页面刷新
- 外部事件：
- onPushReceived：收到推送消息，RN 页面弹窗提示
- onAppBackground：App 进入后台，RN 暂停耗时操作（如视频播放）
五、实施步骤与保障措施
1. 分阶段实施计划
第一阶段：基础集成
- 搭建 RN 开发环境（Node、Xcode/Android Studio 配置）
- 原生项目集成 RN 基础框架，跑通第一个 RN 页面（如 “关于我们”）
- 实现 3-5 个核心交互接口（如获取用户信息、网络状态）
第二阶段：功能验证
- 迁移 1-2 个简单业务页面（如 “帮助中心”“活动列表”）到 RN
- 部署热更新服务（如使用 CodePush 或自建服务器），验证 Bundle 动态下发
- 测试三端一致性（UI、交互、性能）
第三阶段：全面推广
- 逐步迁移非核心业务（如营销活动、内容展示页）
- 完善监控体系（RN 崩溃率、页面加载时间）
- 制定原生与 RN 开发规范，同步团队技术培训
2. 热更新策略
Bundle 管理：
- 服务器存储多版本 Bundle（按业务模块拆分，减少下载体积）
- 客户端启动时检查版本，静默下载最新 Bundle（仅首次或版本更新时）
版本控制：
- 每个 Bundle 关联版本号（如v1.2.0），支持灰度发布（按用户群 / 地区）
- 异常时自动回滚到上一稳定版本
安全性：
- Bundle 文件加签校验，防止篡改
- 敏感操作（如支付）仍保留原生实现，避免 RN 逻辑被破解