React 企业级应用架构方案

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

一、 核心基础

二、 架构模式：单仓库多入口 (MPA)

项目采用 单仓库多入口 (MPA) 的架构模式，将管理系统 (Admin/App) 与 数据可视化大屏 (Screen) 等不同业务场景解耦。

2.1 目录结构

src/
├── components/      (公共组件库)
├── hooks/           (公共自定义 Hooks)
├── service/         (统一服务层: Axios 封装 + Handler 模式)
├── utils/           (工具函数)
├── types/           (TypeScript 类型定义)
└── project/         (业务项目目录)
    ├── admin/       # 管理后台代码 (入口1)
    ├── screen/      # 数据大屏代码 (入口2)
    └── index.html   # 入口重定向/主页

2.2 MPA 配置优势

• 资源隔离: 管理后台依赖 AntD，大屏依赖 ECharts/Skia，MPA 独立打包，避免资源冗余。
• 独立部署: 不同入口可应用不同的缓存策略或路径管理（如 / 与 /screen）。
• 共享基础能力: 统一的 Service、Utils 和 Hooks，避免重复定义 API。

三、 核心库与工具

3.1 Ant Design (UI 组件库)

• 用途: 企业级后台管理系统的标准 UI 解决方案。
• 最佳实践: 配合 ConfigProvider 统一配置主题色、语言包及组件默认属性。

3.2 ahooks (实用 Hooks 库)

• 用途: 阿里巴巴出品的高质量 Hooks 库。
• 核心功能:
  • useRequest: 统一管理异步请求状态（Loading、Success、Error）。
  • useAntdTable: 简化 AntD Table 与分页逻辑的绑定。
  • useSize / useHover: 增强的 DOM 交互 Hooks。

3.3 autofit.js (屏幕适配)

• 场景: 针对 数据可视化大屏 的等比缩放适配。
• 实现: 在布局组件中初始化，基于设计稿尺寸（如 1920x1080）自动计算缩放比例，确保在任何分辨率下不失真。

四、 状态管理与数据流

推荐采用 MobX / Zustand 与 ahooks (useRequest) 结合的方案。

4.1 状态管理选择

• MobX: 适用于逻辑复杂、数据关联性强的管理后台，通过响应式自动更新 UI。
• Zustand: 适用于轻量级、简单的全局状态（如用户信息、主题配置）。

4.2 数据流封装 (Handler 模式)

通过 createHandler 工厂函数统一封装 API 请求，实现请求参数与业务逻辑的解耦，支持动态 BaseURL 和统一错误拦截。

五、 样式方案

推荐采用 Tailwind CSS 与 Ant Design 结合。

• Ant Design: 负责复杂的业务组件（Table, Form, Modal）。
• Tailwind CSS: 负责灵活的页面布局、间距及原子化样式定制。

六、 权限控制与安全

6.1 路由鉴权 (RouteAuth)

使用 RouteAuth 包装组件实现声明式鉴权，根据 userInfo 中的权限标识或角色动态控制页面访问。

6.2 令牌管理

• APP: 使用 access_token 鉴权，过期引导至登录。
• Screen: 采用长效 Token，确保大屏长时间稳定运行免登。

七、 生产环境优化

• 代码分割: 配合 React.lazy 实现路由级别的按需加载。
• Tree-shaking: 针对 AntD 和 ahooks 配置按需引入，减小包体积。
• 环境管理: 使用 .env 管理多套后端环境（Dev, Staging, Prod）。

八、 项目架构图示例

App 入口
├── ConfigProvider         (AntD 全局配置)
│   └── StoreProvider      (MobX/Zustand 状态)
│       └── RouterProvider (路由中心)
│           ├── Layout     (公共布局)
│           │   ├── Header
│           │   ├── Sidebar
│           │   └── Content (Outlet)
│           └── GlobalToast (全局通知)

最后更新: 2026年4月