React Native 统一技术栈方案

本文档总结了推荐的 React Native 企业级应用开发技术栈、核心库、架构方案与最佳实践。该方案结合了多个项目的实战经验，旨在提供高性能、可维护且易于扩展的移动端开发蓝图。

一、 核心基础

二、 状态管理与持久化

2.1 Zustand (轻量级状态管理)

• 优势: 极简 API，免去 Provider/Context 嵌套，支持高性能的 selector 订阅。
• 最佳实践: 按业务模块划分 Store，通过 selector 访问以减少不必要的重渲染。

2.2 MMKV (高性能本地存储)

• 库: react-native-mmkv
• 用途: 替代传统的 AsyncStorage，提供同步读写能力，性能提升显著。
• 场景: 存储 Token、用户基础配置、服务器地址等关键持久化数据。

三、 样式与主题方案

推荐采用 原子化 CSS (NativeWind) 与 类型安全主题 (Restyle) 结合的方案。

3.1 NativeWind (Tailwind CSS)

• 用途: 使用 Tailwind CSS 快速构建 UI，实现原子化样式。
• 配置: 配合 tailwind.config.js 定义自定义主题色与扫描路径。

3.2 Shopify Restyle (布局与 Token 化)

• 用途: 定义类型安全的主题系统，统一管理 spacing、colors、textVariants。
• 适配: 配合 autofit 工具函数实现响应式尺寸适配（如基于 1080p 或 720p 设计稿）。

3.3 React Native Paper (组件库)

• 库: react-native-paper
• 用途: 提供成熟的 Material Design 3 (MD3) 组件，支持高度自定义主题。

3.4 小暑 (Xiaoshu UI)

• 特点: 轻量级、高性能的 React Native 基础组件库。
• 用途: 针对企业级应用优化的 UI 组件，支持高度自定义与快速原型开发。

四、 导航方案

4.1 React Navigation

• 核心库: @react-navigation/native + @react-navigation/native-stack
• 特点: 使用 NativeStack 导航器，利用原生页面切换性能。
• 全局导航: 封装 navigationRef 实现组件外跳转，解耦业务逻辑与 UI 结构。

五、 网络请求与数据处理

5.1 Axios 封装 (createHandler 模式)

• 工厂模式: 通过 createHandler 统一封装请求逻辑。
• 功能点:
  • 动态 BaseURL: 支持从 MMKV 动态读取并切换服务器地址。
  • 拦截器: 统一注入 Authorization Header，处理 HTTP 错误状态码。
  • 业务适配器: 统一判断业务成功/失败状态（如 code === 200）。
  • 错误处理: 集成全局 Toast 提示与离线检测（NetInfo）。

5.2 ahooks (useRequest)

• 用途: 简化异步请求状态管理（Loading、Success、Error），支持轮询、缓存与依赖请求。

六、 动画、手势与高性能组件

6.1 动画与交互

• Reanimated: 实现 60fps 的 UI 线程动画，零 JS Bridge 开销。
• Gesture Handler: 提供流畅的手势识别体验。

6.2 高性能列表

• Flash-list: Shopify 出品，作为 FlatList 的高性能替代品，显著减少列表掉帧。

6.3 图形与媒体

• Skia: 高性能 2D 绘图引擎，适用于复杂滤镜、渐变与图形动效。
• Expo Image: 支持缓存、渐进式加载与多种格式（WebP, SVG）的高性能图片组件。

七、 架构设计与工程化

7.1 路径别名

使用 babel-plugin-module-resolver 配合 tsconfig.json 实现语义化引用：

• @/* → src/*
• @modules/* → modules/*

7.2 版本管理自动化

• 策略: 以 package.json 为唯一事实来源 (SSOT)。
• 自动化脚本: 编写脚本自动将版本号同步至 app.json、Android build.gradle 与 iOS project.pbxproj。

7.3 响应式适配 (Autofit)

通过工具函数根据设备屏幕宽度自动缩放设计稿尺寸，确保在不同屏幕分辨率下布局一致。

7.4 生产环境优化

• 代码压缩: 使用 babel-plugin-transform-remove-console 移除生产环境日志。
• 按需引入: 针对组件库配置 Babel 插件实现 Tree-shaking。

八、 进阶模块 (可选)

根据项目需求集成以下能力：

• 硬件通信: 基于原生模块（Kotlin/Swift）实现的串口通信 (Serial Port) 或 TCP Socket。
• 多媒体: react-native-vision-camera 实现人脸识别与扫码。
• 语音能力: react-native-tts 集成（如讯飞 TTS 引擎）实现离线语音播报。
• OTA 更新: 基于 expo-updates 或自定义 APK 下载安装流程实现热更新。

九、 项目架构图示例

App.tsx
├── SafeAreaProvider           (安全区域适配)
│   └── GestureHandlerRootView  (手势交互根)
│       └── RestyleProvider     (布局/间距主题)
│           └── PaperProvider   (MD3 组件主题)
│               ├── StatusBar   (状态栏管理)
│               └── Navigation  (路由中心)
│                   ├── AuthStack   (登录流程)
│                   └── MainStack   (业务流程)

最后更新: 2026年3月