# 代码规范

<!-- TOC -->

- [代码规范](#代码规范)
  - [规范可提出异议](#规范可提出异议)
  - [解决所有警告和错误](#解决所有警告和错误)
  - [git 使用规范](#git-使用规范)
    - [检查提交的每行代码](#检查提交的每行代码)
    - [避免生成菱形合并记录](#避免生成菱形合并记录)
  - [公共组件和服务](#公共组件和服务)
  - [组件文件](#组件文件)
  - [命名规范](#命名规范)
    - [文件命名](#文件命名)
    - [组件命名](#组件命名)
    - [路由命名](#路由命名)
    - [localStorage 键值命名](#localstorage-键值命名)
    - [filter 命名](#filter-命名)
    - [service 命名](#service-命名)
    - [自定义事件命名](#自定义事件命名)
    - [slot 命名](#slot-命名)
  - [组件样式](#组件样式)
    - [class 命名](#class-命名)
    - [设计资源](#设计资源)
      - [例外](#例外)
    - [内联样式](#内联样式)
      - [例外](#例外-1)
  - [请求后台数据](#请求后台数据)
    - [导入 axios](#导入-axios)
    - [相对路径](#相对路径)
  - [Vuex](#vuex)
    - [避免滥用](#避免滥用)
    - [模块化](#模块化)
  - [其他](#其他)

<!-- /TOC -->

## 规范可提出异议

所有规范都是为了保证代码质量、提高协作效率

如果对哪条规范有疑问或者不同意见，可以随时提出

## 解决所有警告和错误

项目内置了多种代码检查的规则，提交到 git 前需要解决所有警告和错误

## git 使用规范

### 检查提交的每行代码

为了避免将调试代码、实验性代码、误操作修改的代码等提交到 git，需要在提交前通过自带的代码对比功能，检查每一处代码的修改是否为本次功能所必须的。

### 避免生成菱形合并记录

如果每次拉取代码使用 pull+merge 模式的话，后续提交时会出现多个父节点的菱形合并记录，造成团队其他成员查看修改记录的不便

所以拉取代码时应该使用 rebase 模式，详细信息可参考[简单对比 git pull 和 git pull --rebase 的使用](https://juejin.im/entry/5b19fef2e51d4506a81b6078)

## 公共组件和服务

common 目录下的内容是各模块公用的，所以不要直接修改

现有组件、服务不满足需求的，可以提需求单，由专人统一修改

在模块开发过程中，如果发现一些功能应该提炼为公共部分，也可以提需求单

## 组件文件

请保持[使用模板创建](../../README.md#快速新建组件)时生成的文件结构

将请求/整理后台数据的部分放到独立的 service 中

便于后期项目单独覆盖某一项

## 命名规范

### 文件命名

采用 `kebab-case` 格式，例如 `sd-nav-menu.js`

避免 linux 系统下文件名大小写的问题

### 组件命名

平台组件（包括通用组件、router-view 中的页面）以 `Sd` 开头，例如 `SdNavMenu`

增加 `Sd` 前缀一方面是避免与 HTML 未来新增的元素名冲突

另一方面是避免与后续产品和项目定制的组件名冲突

[使用模板创建](../../README.md#快速新建组件)时会自动处理这些命名问题，按提示操作即可

### 路由命名

路由中的 path 和 name 都需要以 `sd-` 开头，例如 `/sd-login`

避免与后续产品和项目定制的组件名冲突

### localStorage 键值命名

请通过 sdLocalStorage 服务存取数据，例如 `sdLocalStorage.setItem(key, value)`

会自动增加 `sd-` 前缀，避免和产品项目的重名问题，后续会添加 `xmLocalStorage` 供项目使用

### filter 命名

全局注册的 filter 文件名需要以 `sd-` 开头，避免和产品项目的重名问题

并放到 common/filters 目录下，会被自动注册为全局 filter

局部注册的 filter 命名无特殊要求

### service 命名

由于 service 并非全局注册，通过 ES module 可以很好的处理重名问题

所以 servcie 无需特殊前缀。例如 `eventBus`、`routerService`

### 自定义事件命名

在 Vue 规范中要求时间名采用 `row-clcik` 格式，但为了和 ant-design-vue 保持一致，我们要求使用 `rowClick` 格式

### slot 命名

使用 `kebab-case` 格式

## 组件样式

样式使用 scss 文件，并启用 CSS Module

### class 命名

class 命名时直接使用其语义命名即可，如 `.logo`，无需增加其他组件相关的前缀

编译后会自动追加组件名和模块名，如 `.logo_sd-frame_workbench`

### 设计资源

禁止在 scss 中直接写色值、字号等，要从已有变量中读取。以便于后续更换主题时样式保持一致。例如：

```scss
.wrapper {
  // 文字颜色设置为“反色文字（黑底白字）”（不能直接写white）
  color: $text-color-inverse;
  // 背景色设置为主题色（不能直接写#1DA57A）
  background: $primary-color;
}
```

所有变量位于 `src_custom/design/index.scss`，需要时可以从中查找适合的变量

此文件组件模板已默认导入

#### 例外

假设有如下设计稿，本身就是五颜六色的，他并不需要在更换主题的时候自动改变颜色：

<img src='http://172.20.90.139/xcoa/xcoa-web/raw/develop/docs/assets/static-color.png'>

所以这部分样式可以不使用主题相关的颜色（如`$primary-4`），直接用设计资源中精选的静态色值

<img src='http://172.20.90.139/xcoa/xcoa-web/raw/develop/docs/assets/colors.png'>

### 内联样式

禁止直接用 style 标签写样式，以便于项目使用适合的 css 选择器覆盖样式

需要按条件切换的样式（例如左侧导航收起和折叠），可以用 :class 表达式动态切换 class

#### 例外

不适合通过切换 class 实现的（例如需要复杂计算、运行时才能确定），可以使用 :style 表达式

## 请求后台数据

### 导入 axios

使用 `import axios from '@/common/services/axios-instance'`导入

而不是`import axios from 'axios'`

以便于我们修改各种默认行为，同时不影响原始库的使用

### 相对路径

发送请求时，应该使用相对路径。例如：`api/framework/v1/user-tasks/todo`

以适应代码部署到不同 appname 下的情况

## Vuex

以下规则的实践，可以参考 `src/login/store.js`

### 避免滥用

尽量把数据保存在组件的 state 中，通过 props 传递到子组件

除非有绝对的必要，才把数据保存到 Vuex 中

使用 Vuex 的情况下要避免使用 actions，相关异步请求应该放到 service 中

Vuex 只做数据存储用途

### 模块化

放在模块目录下的 store.js 会被自动注册进全局 Vuex 实例，并启用 namespace

## 其他

其余部分按照 [Vue 官方代码风格指南](https://cn.vuejs.org/v2/style-guide/) 执行