Vue项目代码规范与最佳实践

Vue项目代码规范与最佳实践

该份代码规范适用于基于Vue技术栈的中台项目。

代码规范

Vue组件

javascript

1. import文件依次导入顺序为：安装的npm模块，@路径文件，相对路径文件，不同类型的文件要显式地用空行间隔。示例：

import lodash from 'lodash'

import EnhanceInput from '@/components/enhance-input.vue'
import EhanceSelect from '@/components/enhance-select.vue'

import InsideIcon from './components/inside-icon.vue'

import './style.css'

2. import导入时对于非JS类型的文件，需要显式的写入该文件的扩展名。这样做的目的在于在VS Code中配置好该项目的jsconfig.json文件后，可以友好的进行组件定义跳转。示例：

// good
import EnhanceInput from '@/components/enhance-input.vue'
// bad
import EnhanceInput from '@/components/enhance-input'

3. 对于单文件组件，在定义时，需要显式的定义其name值，这样在使用vue-dev-tool工具时，可以很好的显式整个节点树的信息。为了补充组件的中文描述信息，推荐定义字段cnName。示例：

// good
export default {
  name: 'EnhanceInput'，
  cnName: '增强的输入框控件'
}

4. 对于组件中的template, javascript, style部分，需要用空行进行间隔。
5. 对于页面组件的分页参数，将其存放到当前的页面组件中，而不是对应的store模块中，这样做，方便在是使用keep-alive特性时，复用页面组件，对分页参数的友好处理。
6. 针对第5条提出的操作，在进行页面列表数据请求时，将获取到的列表数据大小返回到当前页面中，并更新对应分页参数的字段的值。
7. function code 适当的换行，声明语句，函数调用语句，循环语句之间推荐用空行间隔，这样做的目的是更好的代码可读性。
8. 函数名，或者方法名，要命名的有尽量精确，语义化，不要担心长度问题，这是压缩插件应该考虑的事情。
9. 变量，函数，函数参数，类的方法/属性使用 Camel 命名法。
10. 常量使用 全部字母大写，单词间下划线分割 的命名方式。
11. Promise对象 用 动宾短语的进行时 表达，示例：

const loadingData = requeset.get('url')

loadingData.then(callback)

12. 不要使用3层及以上的解构。过多层次的解构会让代码变得难以阅读。
13. 对于深层次（超过3层）嵌套的对象，考虑使用 递归 的手段去处理，而不是硬编码去处理。
14. 使用Object.keys 或者 Object.entries 进行对象遍历，以避免遗漏hasOwnProperty产生的错误，示例：

// good
for (let key of Object.keys(foo)) {
    let value = foo[key];
}

// good
for (let [key, value] of Object.entries(foo)) {
    // ...
}

15. 不要使用jQuery，操作DOM请使用原生语法。
16. 在想要抛出Error以提醒错误的函数调用时，需考虑到开发环境和生产环境的不同，显式地抛出错误要在开发环境处理，而在生产环境应该替换为对用户更为友好的错误提示。具体可查看Vue源码的错误处理代码。

template

1. 对于template部分，在组件的根元素添加对应的class，方便后续写css部分，控制组件内样式的优先级。
2. 使用v-for指令时，使用数组的索引设置数组成员的key值。示例：

<li v-for="(item, idx) in list" :key="idx">{{item}}</li>

Vue官方文档中有写：

你也可以用 of 替代 in 作为分隔符，因为它更接近 JavaScript 迭代器的语法：
所以这里推荐尽量使用of关键字

3. 在写模态框相关的代码时，不要使用v-if来控制模态框的显示，而是通过.sync修饰符来控制属性show，从而控制模态框的显示。

style

1. 使用scoped特性来约束css规则的范围
2. 正确使用Display的属性：
   a) display:inline后不应该再使用width、height、margin、padding以及float
   b) display:inline-block后不应该再使用float
   c) display:block后不应该再使用vertical-align
   d) display:table-*后不应该再使用margin或者float

项目结构组织

1. 对于跨页面使用的业务组件，将其存放到 src/views/index/_components/ 目录下
2. 对于基础控件，封装的三方组件，将其存放到 src/components/ 目录下。
3. 对于项目用到的mixin,directive文件，将其统一存放到 src/mixins/ 类似的目录下
4. 对于mutation文件中使用的type变量，将其统一存放到 src/constants/mutation-type.js 文件下，而不是在store中再新建相应的文件
5. 开发环境中用于测试，验证原型的Demo文件，将其存放到 src/views/index/_Demo/ 目录下

其他

1. 对于接口请求，将其存放到 src/apis/ 目录下，并按项目领域归类，而不是依照store模块进行划分。

最佳实践

代码可读性

1. 数组迭代循环选择更好的语义API，示例：

// good
const list = []
// 对于list返回新的数组
const newList = list.map(callback)
// 对数组中每个元素处理
list.forEach(item => {
  // doSomething(item)
})
// bad
// 对于list返回新的数组
const newList = []
list.forEach(item => {
  newList.push(item)
})
// 对数组中每个元素处理
list.map(item => {
  // doSomething(item)
})

2. 判断数组类型使用更现代化的API，示例：

// good
Array.isArray(list)
// bad
list instanceof Array

3. 数值类型转化使用Number方法，示例：

const str = '56'
// good
const num = Number(str)

// bad
const num = +str

4. 数值取整操作，优先可读性（除非你是在写一个工具库文件），示例：

// good
const n = Math.floor(3.14)

// bad
const n = ~~3.14

V8优化技巧

1. 尽量保持函数的功能的单一性
2. 不要从未初始化的或已经被删除的元素上加载内容
3. 不要写过于庞大的函数，因为他们更难被优化。同样，不要写过于庞大的js文件，在单纯的js文件中，ESLint推荐代码行数保持在350行以下。

注意：当心性能陷阱，过度优化，永远不要过度优化代码，直到你真正需要。现在经常可以看到一些基准测试，显示 N 比 M 在 V8 中更为优化，但是在模块代码或应用中测试一下会发现，这些优化真正的效果比你期望的要小的多。

其他

1. 为项目添加单元测试
2. 对于复杂的业务流程，或者其他在开发过程中的问题，及时将其产出为实际的文档，将文档存放到 /docs/ 目录下，方便后续对代码的维护。
3. 对于全局通用的接口，并且其内容基本不会变化，应做相应的接口数据缓存处理。
4. 对于项目入口而言，在 src/index/ 目录下，应该只存在三样文件：main.js,App.vue,router.js

后言

这份规范并不完善，其中某些规定可能因人而异而持不同意见，总之，如果你有更好的想法与建议，请评论到下方。
为什么我们要建立这么一份文档呢？我认为规范的编程可以有效地保证整体代码的可读性，可维护性。并对后续的bug修复更加友好。因此，引出一个问题：对于实现同一个功能的两份代码，一个侧重于可读性，一个侧重于性能。那么，对于可读性和性能，你要如何做两者之间的取舍呢？

参考链接

1. 编写高性能的JavaScript代码
2. Baidu EFE team specifications
3. frontend-guidelines
4. 编写更加稳定/可读的javascript代码