前言
在项目开发中,通常都会涉及到多人合作,那么经常就会出现代码风格不一致、提交信息混乱甚至还有代码报错的情况。有可能从远程仓库拉取下来的代码与你的本地代码只是格式不一致而引起冲突或者不是你使用的代码风格,还得去修复和调整。
为了统一代码风格,规范编码规则,规范化 git 提交信息以减少隐藏的 bug、提高团队合作开发效率,制定一个代码规范与提交规范是有用的,也是必要的。
规范流程
就个人理解开发规范流程包含了代码语法规则检查(Linter
)、代码风格格式化(Formatter
)以及 git 提交校验(Pre-Commit Check
)等。
代码语法规则检查:主要是指利用一些代码检测工具(如
ESLint
、TSLint
等)对语法规则和代码风格进行检查、提示以及自动修复。比如禁止使用==
、禁止在变量定义之前使用它们等,其中的校验规则是可以根据团队和个人的习惯自由配置的。代码风格格式化:是指利用一些代码格式化工具(如
ESLint
、Prettier
等)根据设定规则重新输出格式规范的代码,以避免因不同成员代码风格不一致而产生冲突和带来的代码阅读、理解成本。git 提交校验:是指在代码提交时,调用
pre-commit
钩子对代码语法和代码风格进行检查和修复,调用commit-msg
钩子对 commit message 进行校验。若校验未通过,则提交失败,并抛出相应错误。
开发规范流程如下图所示:
![b8628d2fbb23ffbd74c46ca08a38ba20.png](https://i-blog.csdnimg.cn/blog_migrate/26b6c2f0c3eb93906e310f3535a8f6a8.png)
代码语法规则检查
代码语法规则检查工具以ESLint
为例,简单讲解下ESLint
的安装和配置。
ESLint 安装
npm install eslint --save-dev
初始化 ESLint 配置文件
eslint --init
执行上述命令,根据提示选择相应选项后,在项目根目录下,就会生成一个.eslintrc
文件。该文件就是ESLint
的配置文件,所有的规则、拓展都可在此文件中进行配置。
配置过程如下图所示:
![9e60c786fcd928e3800cac0ec7ab6666.gif](https://i-blog.csdnimg.cn/blog_migrate/c9c7f922d0e3cfb36bb2e6a164c3499a.gif)
一个.eslintrc.js
文件如下所示(注意所选环境和语言不同,生成的配置文件内容是有差异的):
module.exports = {
env: {
browser: true, // 在浏览器运行
es2020: true, // 支持ES2020
},
// 继承的规则集
extends: ["eslint:recommended", "plugin:react/recommended"],
// 解析器配置
parserOptions: {
ecmaFeatures: {
jsx: true,
},
ecmaVersion: 11,
sourceType: "module",
},
// 插件集
plugins: ["react"],
// 规则重写
rules: {},
};
ESLint 规则配置
在.eslintrc
文件中,我们主要关注rules
字段,用于重写和配置ESLint
规则。一个简单的规则配置如下所示:
"rules": {
"no-undef": 2, // 禁止使用未声明的变量
"linebreak-style": ["off"], // 不校验换行方式
"quotes": ["error", "double"], // 必须使用双引号
"semi": ["warn", "always"] // 推荐加上句末分号
}
其中如"no-undef"
等是ESLint
中规则的名称。第一个值是错误级别,可以是下面的值之一:
"off"
or0
- 关闭规则"warn"
or1
- 将规则视为一个警告(不会影响退出码)"error"
or2
- 将规则视为一个错误 (退出码为 1)
其余的值表示规则配置选项,每条规则有各自的配置选项。完整的规则及配置可前往ESLint 官网查看。
ESLint 命令
eslint [options] [file|dir|glob]*
常用的 options 如:
--ext
指定对哪些后缀文件进行ESLint
校验,如eslint --ext ts,tsx,js,jsx src/
--fix
对错误进行自动修复,如eslint --ext js,jsx src/ --fix
--init
初始化ESLint
,生成.eslintrc
文件--help
显示所有ESLint
options
eslintignore 文件
有时我们希望对某些文件和文件夹忽略ESLint
检查,可在项目根目录添加.eslintignore
文件,添加上要忽略的文件路径即可。
node_modules
dist
test/**/*.js
build
public
代码风格格式化
ESLint
插件其实也能实现部分代码风格格式化,不过我个人倾向将语法检查和代码风格格式化分离。我们使用ESLint
插件来完成语法检查和修复,在代码风格格式化这块,选择了Prettier
插件,它可以对 HTML/CSS/JS/JSON/Markdown 等大多数语言进行格式化并且配置也是相当简单的。
Prettier
格式化代码过程及前后对比可如下图所示:
![8adfcf40e5e71e714726d6521449e56f.gif](https://i-blog.csdnimg.cn/blog_migrate/3d258edff6ebe6c6e7fc21327dee0736.gif)
Prettier 安装
npm install --save-dev --save-exact prettier
创建 prettierrc 配置文件
在项目根目录下,新建一个.prettierrc.js
文件,添加你的规则,示例如下所示:
module.exports = {
tabWidth: 4,
semi: false,
singleQuote: true,
// ...
};
完整的配置及说明可在Prettier 官网进行查看。
Prettier 命令
npx prettier [options] [file|dir|glob]*
常用的 options 如:
--check
检查指定文件是否符合配置文件所定义的格式规则--write
格式化指定文件--help
显示所有Prettier
options
prettierignore 文件
如果某些文件不需要Prettier
格式化,可在项目根目录添加.prettierignore
文件,添加上要忽略的文件路径即可。
# Ignore artifacts:
build
node_modules
public
关闭 ESLint 格式规则
需要安装eslint-config-prettier
插件来关闭所有不必要的规则或可能与Prettier
冲突的规则以解决ESLint
和Prettier
规则冲突的问题。
npm install --save-dev eslint-config-prettier
然后,将prettier
添加到.eslintrc.*
文件中的extends
数组的最末位置,这样它就能覆盖其他配置。
extends: [
'eslint:recommended',
// ... other extends
'prettier'
],
git 提交校验
git 提交校验是指调用 git 钩子(hook
)进行提交前校验(pre-commit check)和提交信息校验(commit-msg check)。提交前校验即运行 ESLint
命令和 Prettier
命令,以检查代码语法和格式化代码风格。提交信息校验则是对 commit 信息进行检查,以确定其是否为符合预设规则的规范化的 commit 信息。如果钩子检测出错,则阻止提交代码并抛出错误原因。
为了更方便的编写和使用 Git hooks,我们需要借助一些三方库,husky
、lint-staged
、commitlint
简介
husky
husky 能够帮你阻挡住不好的代码提交和推送,正如其名,这个库的作用就是看家护院的二哈 ?。
lint-staged
lint-staged
是一个针对暂存的 git 文件运行 linters 的三方库。通常,我们会在提交代码时进行语法校验、代码格式化和提交信息规范校验。lint-staged
可以让这一系列操作只作用于暂存区的文件,可以有效的减少脚本运行时间。
commitlint
commitlint
用来检测提交信息,它会检查您的提交信息是否符合设定的提交格式。
一个规范正确的 commit 信息应该体现出该次提交是针对哪个模块(scope)进行了哪种类型(type)的具体的更改(subject),默认的提交格式为:
type(scope?): subject # scope is optional
一些规范化的 commit 例子如下所示:
fix(react-dom): unnecesary path on DOMEventProperties
chore: update typescript-eslint monorepo to v3
feat(登录): 添加手机号登录功能
安装
npm install --save-dev husky lint-staged @commitlint/cli
编写 commitlint 配置文件
前往Commitlint Github,可看到有许多基于 commitlint
的共享配置可供选择和使用。
以@commitlint/config-conventional
这个配置文件为例,首先,进行安装:
npm install --save-dev @commitlint/config-conventional
然后,在项目根目录下新建一个commitlint.config.js
文件,并添加以下内容:
module.exports = {
extends: [ '@commitlint/config-conventional' ],
};
若要覆盖默认规则,可通过rules
字段重写规则即可,如
rules: {
'type-case': [2, 'always', 'lowerCase'], // type 须为小写
}
完整的规则列表和配置,可前往commitlint 官网查看。
husky 与 lint-staged 配置
在 package.json
文件中,添加上husky
与lint-staged
的相关配置
"husky": {
"hooks": {
"pre-commit": "lint-staged",
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
},
"lint-staged": {
"src/**/*.{js,jsx,ts,tsx}": [
"eslint --fix"
],
"*.{js,jsx,ts,tsx,scss,less,css,json}": [
"prettier --write"
]
}
效果查看
通过上述步骤,我们已经完成了ESLint
、Prettier
、husky
、lint-staged
以及commitlint
的配置。试着修改一些代码并提交,整个提交校验过程如下所示:
总结
本文完整细致的介绍了如何制定前端代码规范,包括 ESLint
和 Prettier
的安装、配置以及常见命令,还讲解了 git 提交校验相关的库的运用和配置。通过制定这些规范并要求团队成员严格按照此规范进行开发,这样既有助于团队的合作开发,也能减少一些隐藏的 bug。
当然,借助插件只是秉承着不重复造轮子的宗旨,同时也免去了造轮子的麻烦。因为最重要的,还是要选取和制定适合自己和团队的规范。通过灵活的规则配置和适当的自定义拓展,很容易形成团队的沉淀。
参考链接
1. https://eslint.org/ 2. https://prettier.io/ 3. https://github.com/typicode/husky 4. https://github.com/okonet/lint-staged 5. https://commitlint.js.org/关于我
如果觉得本文还不错,希望大家分享、点赞,本公众号前端快爆会定期为您推送最新技术文章,全都是硬菜干货~~
本文到此结束,感谢您的阅读,我们下篇文章见。
关注前端快爆
获取更多精彩
前端快爆
![1c55a30c6c3b5bc15507c40483d465b7.png](https://i-blog.csdnimg.cn/blog_migrate/7b5de374a75b18ee6205f3400615a95d.jpeg)
点下"在看",你最好看