架构设计

[leevare]

关键技术描述

本次页面开发采用React实现一个单页面的PC端网页。通过React Router实现路由的跳转与重定向，使用Redux来维持页面间的统一状态。

涉及到的技术栈

1. react 核心库
2. react-router 负责处理页面的路由
3. redux 数据共享
4. rematch redux再封装库
5. immutable 不可变数据处理库
6. ant design UI库
7. push 桌面消息通知
8. umi-request 请求库
9. mock 数据模拟
10. styled-component 作用域样式

模块拆分

• 入口模块
• 认证模块
• 权限模块
• 消息模块
• 错误处理模块
• 状态管理模块
• 日志模块
• 业务相关模块
• UI模块
• 测试模块

组件拆分

• 容器组件和展示组件
• 纯组件和非纯组件
• 有状态组件和无状态组件
• 布局组件和内容组件

分工

公共组件

分为公共逻辑组件、公共展示组件和公共业务组件，公共逻辑组件一般用于认证、鉴权等操作一系列逻辑操作。公共展示组件用于统一维持公共的样式，如头部、底部等。公共业务组件一般将业务相关的复杂展示UI和逻辑封装到一起，常见的有筛选菜单、表格等。

以如下图为例，可以有横向划分和纵向划分两种策略。横向划分是和业务相关，以业务为主线，抽象业务依赖的组件来来进行组件拆分。纵向划分的话，以组件之间的依赖程度进行拆分。

Redux 状态设计

存在如下几个指标：

• 领域数据还是应用数据？领域数据一般放在ReduxStore中，我们通常会将Redux的Store看作一个数据库，存放范式化的数据。
• 状态是否会被多个组件或者跨页面共享？对于全局共享信息，需要让Redux来管理跨越多组件的状态。
• 状态是否需要被镜像化？如果应用要做时间旅行（撤销重做）或者应用持久化，这个状态需要被恢复，那么应该放到Redux中。
• 状态是否需要跨越组件的生命周期？将状态放在组件局部，就会跟着组件一起被销毁。如果希望状态跨越组件的生命周期，应该放到父组件或者Redux Store中。比如一个模态框编辑的数据在关闭后是否需要保留

里程碑

对于一个大项目拆分为多个里程碑, 预估版本发布的时间.
包含这些内容:

• 版本号
• 发布时间
• 包含的主要模块

验证

• 异常情况
• 性能瓶颈
• 风险评估

项目要求和目标

• 浏览器兼容性
• 运行环境. 例如操作系统、小程序等等
• 时间点
• 性能指标要求. 例如首屏指标、数据量指标

文档索引

前端项目开发可能会关联很多文档，这些文档是分散的，在设计文档中需要把它们聚合起来，方便查阅和引用。

• 需求文档
• DEMO, UI设计稿
• 测试用例
• 接口文档
• UI设计规范文档
• 前端规范文档

构建说明

如何编译和运行

存在两种构建方式，局部构建和全局构建。

如何部署或发布

本地开发只需提交源代码到版本管理仓库，服务端Jenkins持续集成，自动检测版本变动并构建。

代码如何组织

编码约定

1. ESLint风格约束
2. 代码分层
   1. Layout通用布局
   2. services后台接口
   3. components业务通用组件
   4. assets本地静态资源
   5. pages业务页面
   6. utils工具库
   7. mocks模拟数据
   8. locales国际化
3. 所有模块添加Readme.md

持续迭代

文档不是一次性的，它应该跟随项目不断的迭代，不然就失去了文档的意义。

CHANGELOG

列出本文档修改的历史纪录。必须指明修改的内容、日期以及修改人

[flyeagleyuan]

认证模块

1. 支持用户名、密码加图形验证码登录
2. 支持手机号加密码登录
3. 支持openId登录
4. 支持第三方系统单点登录

[cherry-xw]

• URL - 访问什么页面
• Data - 显示什么信息
• View - 页面长成什么样
• Action - 对页面做了什么操作
• API Server - Data 数据的来源

组件

antd ui库

router

• umi 以路由为基础，支持配置式路由和约定是路由（动态路由，嵌套路由，权限路由）
• react-router
  • react-router-dom
  • react-router-config

数据获取

特性	umi-request	fetch	axios
实现	浏览器原生支持	浏览器原生支持	XMLHttpRequest
大小	9k	4k (polyfill)	14k
query 简化	✅	❌	✅
post 简化	✅	❌	❌
超时	✅	❌	✅
缓存	✅	❌	❌
错误检查	✅	❌	❌
错误处理	✅	❌	✅
拦截器	✅	❌	✅
前缀	✅	❌	❌
后缀	✅	❌	❌
处理 gbk	✅	❌	❌
中间件	✅	❌	❌
取消请求	✅	❌	✅

数据存储

支付宝前端发展和选择：

• Roof(停止维护)
• Redux(component -> action -> reducer -> state)
  • redux-thunk 是支持函数形式的 action，这样在 action 里就可以 dispatch 其他的 action 了。这是最简单应该也是用地最广的方案吧，对于简单项目应该是够的。
  • redux-promise 和上面的类似，支持 promise 形式的 action，这样 action 里就可以通过看似同步的方式来组织代码。
  • redux-saga 把所有的业务逻辑都放到 saga 里，这样可以让 reducer, action 和 component 都很纯粹，干他们原本需要干的事情
  • dva
    • 数据的改变发生通常是通过用户交互行为或者浏览器行为（如路由跳转等）触发的，当此类行为会改变数据的时候可以通过 dispatch 发起一个 action，如果是同步行为会直接通过 Reducers 改变 State ，如果是异步行为（副作用）会先触发 Effects 然后流向 Reducers 最终改变 State，所以在 dva 中，数据流向非常清晰简明，并且思路基本跟开源社区保持一致
    • 

特性	redux-thunk	redux-promise	redux-saga	dva

数据操作

为 redux 提供数据源，修改容易

• 方案
  • plain object: 配合 combineReducer 已经可以满足需求。同时在组织 Store 的时候，层次不要太深，尽量保持在 2 - 3 层。如果层次深，可以考虑用 updeep 来辅助修改数据。
• 可选
  • immutable.js: 通过自定义的 api 来操作数据，需要额外的学习成本。不熟悉 immutable.js 的可以先尝试用 seamless-immutable，JavaScript 原生接口，无学习门槛。

另外，不推荐用 redux-immutable 以及 redux-immutablejs，一是没啥必要，具体看他们的实现就知道了，都比较简单；更重要的是他们都改写了 combineReducer，会带来潜在的一些兼容问题。

CSS

• scopped
  • styled-components
  • css-modules: 配合 webpack 的 css-loader 进行打包，会为所有的 class name 和 animation name 加 local scope，避免潜在冲突。
• less

组件组织

1. 组件： antd库 + 自定义
2. 业务组件： 包含部分业务，无法提取成通用组件
3. 区块：组件组成的代码片段
4. 页面模版：区块组成

微前端

部分页面根据业务拆分，MPA开发