二、标准化编程规范
前言
当我们在企业开发的时候，如果项目初期没有去制定好一个统一编程规范，随着项目进度发展，最终会导致项目代码杂乱无章，可读性非常差，最终导致项目难以维护。随着几个版本的迭代，最后项目会变成“屎山”一样,维护起来非常痛苦。 所以我们如何制定一个统一的编程规范呢？我认为规范主要分为以下几个方面：
- 编码规范
- 代码提交规范
接下来我打算从这两方面入手制定统一的编程规范
1. 编程规范
1.1 代码检测工具ESLint
这里只做简单介绍，想进一步了解可参考官网：eslint.org/ 中文文档地址：zh-hans.eslint.org/
在之前我们利用脚手架创建项目的时候已经选择使用ESlint，初始化项目已经自动为我们整合好了，可以看到项目中有一个.eslintrc.cjs文件，这个就是ESLint的配置文件
/* eslint-env node */
require('@rushstack/eslint-patch/modern-module-resolution')
module.exports = {
// 表示当前目录即为根目录，ESLint 规则将被限制到该目录下
root: true,
// ESLint 中基础配置需要继承的配置
'extends': [
'plugin:vue/vue3-essential',
'eslint:recommended',
'@vue/eslint-config-typescript',
'@vue/eslint-config-prettier/skip-formatting'
],
// 解析器
parserOptions: {
ecmaVersion: 'latest'
}
}
这里我觉得默认提供的规则就比较合理，如果有些规则与自己意愿有所冲突再去定制化修改。
比如：有一条校验规则为："vue/multi-word-component-names" 表示组件名称必须要多个单词组成，有的时候难免会有一些特殊情况，如果想要关掉这个校验，则需在.eslintrc.cjs添加配置：
module.exports = {
...
...
/**
* 错误级别分为三种：
* "off" 或 0 - 关闭规则
* "warn" 或 1 - 开启规则，使用警告级别的错误：warn (不会导致程序退出)
* "error" 或 2 - 开启规则，使用错误级别的错误：error (当被触发的时候，程序会退出)
*/
+ rules: {
+ 'vue/multi-word-component-names': 0
+ }
}
配置完成后，使用命令自动检测编程规范，根据提示可快速定位到问题代码
npm run lint
1.2 代码格式化工具Prettier
这是一款开箱即用的代码格式化插件，可以直接通过 VSCode 安装整合。想要进一步了解，请参考官网：prettier.io/ 中文地址: www.prettier.cn/
安装插件
在创建项目的时候我们选择了使用Prettier规范代码格式，可以看到一个 .prettierrc.json 的配置文件，这里可以配置我们统一的代码风格:
{
"$schema": "https://json.schemastore.org/prettierrc",
// 不使用尾行分号
"semi": false,
// tab键等于2个空格
"tabWidth": 2,
// 使用单引号
"singleQuote": true,
// 每行最大字符宽度，换行临界值
"printWidth": 100,
// 多行逗号分隔语法中，最后一行不加逗号
"trailingComma": "none"
}
配置完成后，使用命令自动检测代码格式规范，会应用配置自动进行代码格式化
npm run format
TIPS: 这里有的时候会出现与预期不符的情况，有可能是 VSCode 设置与配置项有冲突，可以修改配置或 VSCode 环境配置，使他们保持一致。以前我们习惯将 ESLint 和 Prettier 整合到了一起，让语法校验的同时进行代码的格式化，但是从 ESLint 和 VUE3 提供的脚手架工程默认配置
.eslintrc.cjs可以看出（@vue/eslint-config-prettier/skip-formatting），ESLint 的主要要任务应该是语法的校验，而格式化的工作交给了 Prettier,各司其职。如果最后还是出现爆红或者检测异常，尝试重启一下项目。
2. 代码提交规范
不知道大家是否有过这样的经历，代码提交信息乱写，功能开发和
bug修复分不清楚，想要找之前这里的历史记录时不容易查找。不同的团队之间有不同的标准，现在市面上比较广泛应用的应该是 Angular 团队规范 延伸出的 Conventional Commits specification（约定式提交）。想要进一步了解，可查阅官方网站。
如果每次提交我们都严格按照约定式提交规范，来手动提交代码的话，提交代码将会是一件非常繁琐的事情，好在前辈们早已实现了一些协助插件，接下来将整合这些协助我们代码提交
2.1 使用 Commintzen 规范化提交代码
想进一步了解可参考官方：github.com/commitizen/…
① 全局安装Commitizen
npm install -g commitizen
② 安装并配置 cz-customizable
- 使用 npm 下载
npm i cz-customizable --save-dev
- 在
package.json中添加以下配置
...
"config": {
"commitizen": {
"path": "node_modules/cz-customizable"
}
}
③ 在项目根目录下创建 .cz-config.js 自定义提示文件
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: 打包' }
],
// 消息步骤
messages: {
type: '请选择提交类型:',
customScope: '请输入修改范围(可选):',
subject: '请简要描述提交(必填):',
body: '请输入详细描述(可选):',
footer: '请输入要关闭的issue(可选):',
confirmCommit: '确认使用以上信息提交？(y/n/e/h)'
},
// 跳过问题
skipQuestions: ['body', 'footer'],
// subject文字长度默认是72
subjectLimit: 200
}
④ 使用 git cz 代替 git commit
提交成功后可以看到我们的提交日志
"test(custom): 测试commitizen规范代码提交"
这里的 custome 是默认的 customScope 修改范围，我不喜欢，如果未指定则不要给我显示
修改配置 .cz-config.js，添加自定义的范围，选择空字符串则不会有修改范围。
.....
scopes: ['', 'system', 'portal'],
}
2.2 使用 husky + commitlint 检查提交是否规范
我们使用
git cz代替git commit实现了规范化的提交，但是无法避免有的时候忘记，习惯性使用git commit提交，这个时候我们就需要添加一层校验，来规避这种情况
① 认识 Git Hooks
无论我们怎么变着花的提交代码，最终的执行命令都是 git 工具完成的，而 git 支持在执行某个事件之前或者之后进行一些其他的额外操作，为我们提供了很多事先就定义好的 钩子函数（hooks）
想要进一步了解有哪些钩子可参考官方文档： git-scm.com/book/zh/v2/….这里我只介绍将要用到的两个，
commit-msg,pre-commit.
- commit-msg: 用来规范化标准格式
- pre-commit: 会在提交之前调用
② 使用 commitlint 检查提交的信息
想进一步了解，移步至官方文档：github.com/conventiona…
- 安装
npm install --save-dev @commitlint/config-conventional @commitlint/cli
- 生成配置文件
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
- 打开 commitlint.config.js 增加配置项
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]
}
}
TIPS：确保保存为 UTF-8 的编码格式，否则可能会出现以下错误：
③ 使用 husky 触发钩子，自动完成提交校验
参考官方文档：typicode.github.io/husky/
- 安装
npm install husky --save-dev
- 初始化，生成 .husky 文件夹
npx husky-init
- 添加 commit-msg 钩子，完成自动校验
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1}'
测试一下提交，发现已经生效了
TIPS: 这里有个大坑，我们之前生成的
commitlint.config.js一定要保证是UTF-8编码的，不然这里会报错。
④ 通过 pre-commit 校验编码规范
- 添加钩子
如果之前初始化的时候已经有了，加上执行脚本
npm run lint
npx husky add .husky/pre-commit "npm run lint"
- 随意修改一处文件使其语法校验错误，测试一下
2.3 使用 lint-staged 自动修复格式错误
TIPS: 我在整合这个的时候有这样的疑问，我们既然有钩子了，为什么不直接在钩子里再执行一遍代码格式化脚本，
npm run format而是要去使用 lint-staged 呢？
通过了解后明白，原来 lint-staged 值得被使用是因为，如果我们哪怕只改了 1 个文件，如果通过钩子，提交的时候是要重新去检测校验所有代码，显然是不合适的，而 lint-staged 可以只对即将提交的文件进行检查，确保每次提交都符合规范，这样提升了项目提交效率。
lint-staged 仅仅是一个文件过滤工具，过滤 git 暂存区里的文件
想进一步了解参考官方说明：github.com/okonet/lint…
① 安装
npm install --save-dev lint-staged
② 修改 package.json
{
...
"lint-staged": {
"src/**/*.{js,ts,vue}": [
"eslint --fix",
"prettier --write"
]
},
}
...
③ 修改 pre-commit 钩子中的脚本
# 将 npm run lint 修改为 npx lint-staged
npx lint-staged
④ 故意修改一处语法错误和代码格式错误测试
总结
到这里整体配置就算完成了，简单总结一下，编程规范主要分为两方面：
- 代码格式的规范
- git 提交规范
明确这里使用的一些插件的作用：
- ESlint: 代码检测工具
- Prettier: 代码格式化工具
- commitizen: git 提交规范化工具
- commitlint: 用于检测提交信息规范化的插件
- lint-staged: 过滤需要检测的 git 暂存区的文件插件
转载自:https://juejin.cn/post/7241769361270439991