# 介绍

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

## 安装、启动和打包

安装：

```bash
npm install
```

启动:

```bash
npm start
```

打包:

```bash
npm run build
```

## 技术栈

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

## 目录结构

| 目录            | 说明                                                                                                                                                                                                                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| build/          | 打包产出                                                                                                                                                                                                                                                                                                           |
| config/         | 打包配置文件                                                                                                                                                                                                                                                                                                       |
| node_modules/   | 依赖包                                                                                                                                                                                                                                                                                                             |
| src/assets/     | 图片、字体文件等文件. 在多数情况下，应该把资源文件放在 src/features/下，这种情况可以让应用垂直划分，同时可以更干净的删除资源。                                                                                                                                                                                     |
| src/auth/       | 认证信息是全局的                                                                                                                                                                                                                                                                                                   |
| src/components/ | 全局组件                                                                                                                                                                                                                                                                                                           |
| src/constants/  | 集中放置全局  常量，方便更新 API 的服务器地址等                                                                                                                                                                                                                                                                    |
| src/directives/ | 全局的 directive                                                                                                                                                                                                                                                                                                   |
| src/features/   | 实现业务需求的组件。目标是让尽可能多的相关文件在相同的业务组件内。这使得开发团队可以更好的划分任务。业务组件可以依赖全局元素，如 src/auth, src/components, src/directives，或者依赖其它业务组件。但是业务组件不应该依赖其它业务组件的子组件，它应该使用其它组件的 public API。必要时，子组件可能在业务组件中重复。 |
| src/http/       | 包含非认证  的 HTTP 请求（ 认证的部分应该在 src/auth 中做）。同时包含 router 和 routes。如果 routes 变的很大，可以将它拆分到 src/features 中，然后通过 import 引用。                                                                                                                                               |
| src/store/      | 使用 Vuex 管理状态的单一 store                                                                                                                                                                                                                                                                                     |
| src/styles/     | 全局样式。 局部样式应该放在 src/features/中                                                                                                                                                                                                                                                                        |
| src/utils/      | 共享的工具类。 跟业务有关的  工具方法放在 src/features/中                                                                                                                                                                                                                                                          |
| 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 中给出网址

### 参考资料

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/)