02.标准化编程规范
1. 前言
在日常开发中,随着团队人员的变更,功能迭代,如果没有一套规范约束大家,就会导致项目中的代码充斥着各种代码风格,会导致后期维护起来十分困难,所以有必要去制定一套规范。互联网发展到今天,前辈们自然也想到了这点,所以有很多已经很完善的方案,这里我只介绍 ESlint + Prettier + commitizen + commitlint + lint-staged。
其实我认为养好良好的编程习惯很重要,而且应该定期开展 code review ,否则哪怕再完善的配置,最终也会导致项目变成“屎山”,包括 TS 都是为了项目易于维护,如果自己写项目,我不会加这些配置,影响开发效率,但是为了学习,这个项目我会加上这些配置以及使用 TS
这里我不想过多介绍,因为我认为这些来约束人的东西不是必要的,如果想要配置,可以跟着操作即可,也很简单。个人项目或者不太在意的直接跳过就行。
2. 编程规范
2.1. 代码检测工具 ESLint
这个初始化项目的时候,我就选择安装了,如果你和我选的一样应该是装上的,不过多介绍。想要进一步了解可参考官网 https://eslint.org/ 中文地址:https://zh-hans.eslint.org/。
我认为默认的规则就比较合理,如果想要修改默认规则可以在 .eslintrc.cjs 文件中进行修改,比如默认规则要求 vue
组件名称必须要由多个单词组成,否则会有提示,如果想要修改可以这样修改:
module.exports = {
...
...
/**
* 错误级别分为三种:
* "off" 或 0 - 关闭规则
* "warn" 或 1 - 开启规则,使用警告级别的错误:warn (不会导致程序退出)
* "error" 或 2 - 开启规则,使用错误级别的错误:error (当被触发的时候,程序会退出)
*/
rules: { // [!code ++]
'vue/multi-word-component-names': 0 // [!code ++]
} // [!code ++]
}
使用 npm run lint 可以检测编程规范,根据提示可以快速定位到问题代码。
2.2. 代码格式化工具 Prettier
这个在创建的时候,已经选择安装了, 这是一款开箱即用的代码格式化插件,可以直接通过 VSCode 安装整合。想要进一步了解,请参考官网:https://prettier.io/ 中文地址: https://www.prettier.cn/
如果想要修改代码风格,比如缩进,换行等等,可以看到一个 .prettierrc.json 的配置文件,这里可以配置我们统一的代码风格:
{
"$schema": "https://json.schemastore.org/prettierrc",
// 不使用尾行分号
"semi": false,
// tab键等于2个空格
"tabWidth": 2,
// 使用单引号
"singleQuote": true,
// 每行最大字符宽度,换行临界值
"printWidth": 100,
// 多行逗号分隔语法中,最后一行不加逗号
"trailingComma": "none"
}
使用 npm run format 命令自动检测代码格式规范,会应用配置自动进行代码格式化
这里有的时候会出现与预期不符的情况,有可能是 VSCode 设置与配置项有冲突,可以修改配置或 VSCode 环境配置,使他们保持一致。以前我们习惯将 ESLint 和 Prettier 整合到了一起,让语法校验的同时进行代码的格式化,但是从 ESLint 和 VUE3 提供的脚手架工程默认配置 .eslintrc.cjs 可以看出(@vue/eslint-config-prettier/skip-formatting),ESLint 的主要要任务应该是语法的校验,而格式化的工作交给了 Prettier, 各司其职。如果最后还是出现爆红或者检测异常,尝试重启一下项目。
3. 代码提交规范
避免团队合作时大家提交信息乱写,不利于问题追溯, 现在市面上比较广泛应用的应该是 Angular 团队规范 延伸出的 Conventional Commits specification(约定式提交)。想要进一步了解,可查阅官方网站。用的比较多的应该就是 feat 和 fix
3.1. 使用 Commintzen 规范化提交代码
3.1.1. 全局安装Commitizen
想进一步了解可参考官方:https://github.com/commitizen/cz-cli
npm install -g commitizen
3.1.2. 安装并配置 cz-customizable
官方地址:https://github.com/leoforfree/cz-customizable
- 安装依赖
npm i cz-customizable --save-dev
- 在
package.json
中添加以下配置
{
...
"config": {
"commitizen": {
"path": "node_modules/cz-customizable"
}
},
}
3.1.3. 在项目根目录下创建 .cz-config.cjs 自定义提示文件
module.exports = {
// 可选类型
types: [
{ value: 'feat', name: 'feat: 新功能' },
{ value: 'fix', name: 'fix: 修复' },
{ value: 'docs', name: 'docs: 文档变更' },
{ value: 'style', name: 'style: 代码格式(不影响代码运行的变动)' },
{ value: 'refactor', name: 'refactor: 重构(既不是增加feature,也不是修复bug)' },
{ value: 'perf', name: 'perf: 性能优化' },
{ value: 'test', name: 'test: 增加测试' },
{ value: 'chore', name: 'chore: 构建过程或辅助工具的变动' },
{ value: 'revert', name: 'revert: 回退' },
{ value: 'build', name: 'build: 打包' }
],
// portal 门户,system 后台管理系统
scopes: ['', 'portal', 'system'],
// 消息步骤
messages: {
type: '请选择提交类型:',
customScope: '请输入修改范围(可选):',
subject: '请简要描述提交(必填):',
body: '请输入详细描述(可选):',
footer: '请输入要关闭的issue(可选):',
confirmCommit: '确认使用以上信息提交?(y/n/e/h)'
},
// 跳过问题
skipQuestions: ['body', 'footer'],
// subject文字长度默认是72
subjectLimit: 200
}
在
package.json
添加以下配置, 否则会提示错误
"config": {
"cz-customizable": {
"config": ".cz-config.cjs"
}
}
3.1.4. 使用 git cz 代替 git commit
测试一下提交
可以看到配置生效了,选择填写提交信息后 git push
这里还可以指定 customScope 修改范围,默认为 customer,我不喜欢,如果未指定则不要给我显示 修改配置 .cz-config.js,添加自定义的范围,可根据自己项目情况添加,比如我是按照门户网站和管理系统来区分的,选择空字符串则不会有修改范围。
{
......
scopes: ['', 'system', 'portal'],
}
3.2. 使用 husky + commitlint 检查提交是否规范
我们使用 git cz
代替 git commit
实现了规范化的提交,但是无法避免有的时候忘记,习惯性使用 git commit
提交,这个时候我们就需要添加一层校验,来规避这种情况
3.2.1. 认识 Git Hooks
无论我们怎么变着花的提交代码,最终的执行命令都是 git 工具完成的,而 git 支持在执行某个事件之前或者之后进行一些其他的额外操作,为我们提供了很多事先就定义好的 钩子函数(hooks)
想要进一步了解有哪些钩子可参考官方文档:https://git-scm.com/book/zh/v2/%E8%87%AA%E5%AE%9A%E4%B9%89-Git-Git-%E9%92%A9%E5%AD%90. 这里我只介绍将要用到的两个,commit-msg , pre-commit.
- commit-msg: 用来规范化标准格式
- pre-commit: 会在提交之前调用
3.2.2. 使用 commitlint 检查提交的信息
想进一步了解,移步至官方文档:https://github.com/conventional-changelog/commitlint
- 安装
npm install --save-dev @commitlint/config-conventional @commitlint/cli
- 生成配置文件
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.ts
module.exports = {
extends: ['@commitlint/config-conventional'],
// 定义规则类型
rules: {
// type 类型定义,表示 git 提交的 type 必须在以下类型范围内
// 0:禁用规则,不会对提交类型进行验证。
// 1:警告级别,对提交类型进行验证,但不会阻止提交。
// 2:错误级别,对提交类型进行验证,如果不符合规则将阻止提交。
// 'always':规则始终适用于提交消息中的提交类型。无论提交消息的内容如何,都会应用该规则进行验证。
// 'never':规则永远不适用于提交消息中的提交类型。无论提交消息的内容如何,都不会应用该规则进行验证。
'type-enum': [
2,
'always',
[
'feat', // 新功能 feature
'fix', // 修复 bug
'docs', // 文档注释
'style', // 代码格式(不影响代码运行的变动)
'refactor', // 重构(既不增加新功能,也不是修复bug)
'perf', // 性能优化
'test', // 增加测试
'chore', // 构建过程或辅助工具的变动
'revert', // 回退
'build' // 打包
]
], // subject 大小写不做校验
'subject-case': [0]
}
}
:::warning
确保保存为 UTF-8 的编码格式,否则可能会报错
:::
3.2.3. 使用 husky 触发钩子,自动完成提交校验
https://typicode.github.io/husky/
- 安装
npm install husky --save-dev
- 初始化,生成 .husky 文件夹
npx husky init
- 修改
.husky/pre-commit
npm run lint
- 添加 commit-msg 钩子,完成自动校验
#!/usr/bin/env sh
npx --no -- commitlint --edit ${1}
可以看到检测出我们提交信息不规范
3.3. 使用 lint-staged 自动修复格式错误
我在整合这个的时候有这样的疑问,我们既然有钩子了,为什么不直接在钩子里再执行一遍代码格式化脚本,
npm run format
而是要去使用lint-staged
呢?
通过了解后明白,原来lint-staged
值得被使用是因为,如果我们哪怕只改了 1 个文件,如果通过钩子,提交的时候是要重新去检测校验所有代码,显然是不合适的,而lint-staged
可以只对即将提交的文件进行检查,确保每次提交都符合规范,这样提升了项目提交效率。
t-staged 仅仅是一个文件过滤工具,过滤 git 暂存区里的文件
想进一步了解参考官方说明:https://github.com/okonet/lint-staged
3.3.1. 安装
npm install --save-dev lint-staged
3.3.2. 修改 package.json
{
...
"lint-staged": {
"src/**/*.{js,ts,vue}": [
"eslint --fix",
"prettier --write"
]
},
}
...
3.3.3. 修改 pre-commit 钩子中的脚本
# 将 npm run lint 修改为 npx lint-staged
npx lint-staged
3.3.4. 故意修改一处语法错误和代码格式错误测试
可以看到自动执行了钩子,进行了检测修复
4. 总结
到这里整体配置就算完成了,简单总结一下,编程规范主要分为两方面:
- 代码格式的规范
- git 提交规范
明确这里使用的一些插件的作用:
-
ESlint 代码检测工具
-
Prettier: 代码格式化工具
-
commitizen: git 提交规范化工具
-
commitlint: 用于检测提交信息规范化的插件
-
lint-staged: 过滤需要检测的 git 暂存区的文件插件