# 介绍       .

本项目是作为公司的前端的模板项目。采用的是 Vue 的全家桶技术。

本文档介绍项目如何使用和扩展、采用的技术栈、目录结构和最佳实践等。你不用一次看完所有内容，但是建议在正式开发前完整读一遍文档。

## 安装、启动和打包

安装：

```bash
yarn
```

启动:

```bash
npm start
```

打包:

```bash
npm run build
```

## 浏览器兼容

默认配置 IE11+, Edge, Chrome, Firefox.  
建议配置，去除 IE 的支持，Edge 17+, Chrome 55+(360 安全浏览器 9.1+)。

## 技术栈

Vue 2.x
Vuex 3.x
Vue router 2.x

TODO: 架构图

## 构建工具

vue-cli

## 工具安装

### Chrome 插件

[Vue.js devtools](https://chrome.google.com/webstore/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)

## VS Code 插件

1.  Vetur (Author: Pine Wu)
1.  Prettier (Author: Esben Petersen) # 注意: 其他的 vscode 插件可能导致格式化不一致
1.  REST Client (Author: Huachao Mao)
1.  Quokka.js (Author: Wallaby.js) - optional

## 目录结构

| 目录                | 说明                                                                                                                                                                                                                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| dist/               | 打包产出                                                                                                                                                                                                                                                                                                           |
| docs/               | 技术要点的设计思路                                                                                                                                                                                                                                                                                                 |
| node_modules/       | 依赖包                                                                                                                                                                                                                                                                                                             |
| public/             | 公共目录，供发布                                                                                                                                                                                                                                                                                                   |
| src/assets/         | 图片、字体文件等文件. 在多数情况下，应该把资源文件放在 src/features/下，这种情况可以让应用垂直划分，同时可以更干净的删除资源。                                                                                                                                                                                     |
| src/auth/           | 认证信息是全局的                                                                                                                                                                                                                                                                                                   |
| src/api/            | api 集中管理，以资源角色分组，方便复用                                                                                                                                                                                                                                                                             |
| src/components/     | 全局组件                                                                                                                                                                                                                                                                                                           |
| src/constants/      | 集中放置全局常量，方便更新 API 的服务器地址等                                                                                                                                                                                                                                                                      |
| src/directives/     | 全局的 directive                                                                                                                                                                                                                                                                                                   |
| src/features/       | 实现业务需求的组件。目标是让尽可能多的相关文件在相同的业务组件内。这使得开发团队可以更好的划分任务。业务组件可以依赖全局元素，如 src/auth, src/components, src/directives，或者依赖其它业务组件。但是业务组件不应该依赖其它业务组件的子组件，它应该使用其它组件的 public API。必要时，子组件可能在业务组件中重复。 |
| src/modules/        | 当系统变大，多人负责独立模块时，设立 modules 文件夹，modules 文件夹下包含 api, components, constants, directives, filters, features, routes, store. 即 modules 下是一个小世界，在外部引用各个单独的 module。采用此文件夹时，就不需要 src/features/文件夹了。                                                       |
| src/filters/        | 全局的 filter                                                                                                                                                                                                                                                                                                      |
| src/plugins/        | vue plugins                                                                                                                                                                                                                                                                                                        |
| src/styles/         | 全局样式。 局部样式应该放在 src/features/ 或 src/modules/\*/features 中                                                                                                                                                                                                                                            |
| src/utils/          | 共享的工具类。 跟业务有关的工具方法放在 src/features/中                                                                                                                                                                                                                                                            |
| src/router/index.js | vue-router，可以引用 src/modules 下面的 routes。如果没有划分 module，可以在 src/router 下面写 model，比如 user.js。                                                                                                                                                                                                |
| src/store/index.js  | 使用 Vuex 管理状态的单一 store. 可以引用 src/modules 下面的 store 。如果没有划分 module，可以在 src/store 下面写 page，比如 user.js。                                                                                                                                                                              |
| static/             | 不需要 Webpack 处理的静态文件                                                                                                                                                                                                                                                                                      |
| tests/              | 单元测试和 E2E 测试                                                                                                                                                                                                                                                                                                |

## 错误处理

### 通用的错误处理

#### API 请求

从用户操作，界面有一处集中显示操作反馈。  
处理顺序如下：

1.  用户操作
2.  触发 vue action
3.  调用 vuex action（无需处理错误）
4.  调用 api，若出错，修改全局错误状态，并通知展示状态
5.  界面展示程序状态，即出错信息

如果用户需要 vuex action 的结果，可以在 vuex action 里面返回 promise，不建议在 component 处理状态。
应该尽可能通过 store 的状态更新使得界面更新。

## 状态处理

无需共享状态的组件可以直接在组件的生命周期中发请求获取数据。一般是纯显示的组件比较多。

共享状态的通过 vuex 来处理。

## TODO:

1. module state
2. 新项目以 ES2018 为基准，选择 stage 3 的特性，将常用的特性列表在 readme 中给出网址
3. 目前(2019-01-31)，iview 和 elementui 都已经明确表示它们不支持移动端（在移动端组件的显示不是很完美）。移动端的策略需要另外讨论。[quasar](https://github.com/quasarframework/quasar) [vux](https://github.com/airyland/vux) [vuetify](https://github.com/vuetifyjs/vuetify)
4. animation 以 iview 内部为主。个别地方需要定制的话，可以自制动画，或采用 animated.js
5. iview 处理 less 的主题修改有问题 [github issue](https://github.com/iview/iview/issues/4156) 考虑通过单独的项目来定制主题 [iview docs](https://www.iviewui.com/docs/guide/theme)
6. 路由设计: 目录；auth. 根据用户的角色动态生成 routes？
7. form 校验。form 表单数据与 URL 同步，浏览器后退根据 URL 回填 form，回填时 URL 优先 form 默认值；使用表单查询或翻页时，使用表单数据，然后根据表单数据更新 URL，会造成 component update?
8. 组件传递消息: props, vuex, event
9. 布局建议。侧边栏，顶部导航栏，页脚。内容页。
10. loading.
11. message. global config. 页面内反馈。系统消息。
12. router: component cache
13. 组件可选。比如消息列表。
14. mock。
15. 浏览器探测，提示升级。
16. chart: echarts optional
17. 百度统计
18. sourcemap 在各个环境中的设置
19. \$http 可以统一使用一套，做好错误捕获就可以了。在登录和退出接口设置好 token。

### 参考资料

1.  [Vue-pizza](https://github.com/prograhammer/vue-pizza)
1.  [Error handling with async-await in Vue and Vuex](https://dimitrioslytras.com/vue-error-handling/)