如何从0开始搭建1个前端项目?第二章(统一代码风格篇 - xxx配置文件&xxxLint工具)

如何从0开始搭建1个前端项目?第二章(统一代码风格篇 - xxx配置文件&xxxLint工具)

第二章:统一代码风格篇(.vscode/setting.json&EditorConfig&ESLint&Stylelint&Prettier&husky&lint-staged&commitlint

上一篇:第一章:《初始化项目篇》GtiHub创建项目 & README LICENSE .gitignore & Npm

favicon.svg 所有的源码都在这里(如果觉得对你有帮助,求star支持,感谢!🙏)

4. 统一代码风格

其实在我们平常的项目开发过程中,往往都是团队合作开发,因为大家写代码的风格都会不太一样,那如果我们不去做个统一,那项目后期的维护会变得非常恶心,大家开发起来也会非常难受,所以统一代码风格是一件非常必要的事情,而且在项目开始开发之前就要做好这件事

VScode配置文件

首先我们可以先创建一个VScode配置文件,在项目根目录下创建.vscode/setting.json,这个文件的作用是帮我们定义在当前工作区的编辑器配置,比如下面这行配置就是在保存文件时按照默认的格式化程序自动格式化文件,我们可以帮下面代码拷贝一下,然后在项目中根目录下新建src/index.js,然后写一些代码打乱格式保存一下试一试看效果,是不是很爽?

{
  "editor.formatOnSave": true,
}
复制代码

EditorConfig - 有助于跨各种编辑器和IDE为在同一项目上工作的多个开发人员维护一致的编码样式

我们可以先创建.editorconfig文件,然后下载EditorConfig for VS Code插件(本文中提到的插件都是VScode插件,其它idea或编辑器的插件可以自行去网上找一下,在VScode右边的扩展中直接搜索即可下载),最后拷贝如下代码

root = true

[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
复制代码

上面这几行的配置其实很好理解,editorConfig的配置也一共也就这么多种,支持的功能也比较有限,感兴趣的可以试一试每个配置的效果,比如insert_final_newline = true这句配置的意思就是确保文件以换行符结尾,而插件的效果就是读取我们项目中相应的配置文件然后在保存文件时自动格式化代码,比如这时我们保存文件就会自动帮我们在文件末尾留一个新行

ESLint - 一个插件化的javascript代码检测工具

  1. 首先,我们需要下载eslint,在终端执行npm install eslint,这也是我们下载的第一个依赖包,等待下载成功后,会发现项目中多了一个node_modules的文件夹,这里就是存放项目依赖文件的地方,同时在package.json文件种会多出一个dependencies字段,这里是记录项目所有依赖信息的地方,然后再下载ESLint插件

  2. 其次,我们需要创建.eslintrc.json文件(也可以运行npx eslint --init,什么是npx?)

{
  // 根目录
  "root": true,
  // 环境
  "env": {
    "browser": true,
    "es2021": true,
    "node": true
  },
  // 解析器
  "parser": "espree",
  // 解析器选项
  "parserOptions": {
    "ecmaVersion": 13,
    "sourceType": "module"
  },
  // 继承
  "extends": [
    "eslint:recommended"
  ],
  // 插件
  "plugins": [],
  // 规则
  "rules": {
    /*
      "off" or 0 - 关闭规则
      "warn" or 1 - 将规则视为一个警告(不会影响退出码)
      "error" or 2 - 将规则视为一个错误 (退出码为1)
    */
    "no-console": 1
  }
}
复制代码

注意,有关于eslint的配置还是比较多的,我在上面列出了基本的配置,也写了注释,大多数情况下以上配置其实就已经足够用了,后面我们再按需添加。这里比较重要的一个配置是rules,这里规定按照什么规则去检测代码,比如我配置了"no-console": 1的意思是不允许使用console方法

  • 我们可以尝试在index.js中写上一个console.log(),这时候就能看到eslint给我们以黄色波浪线的方式报错了
  • 我们也可以通过命令行的方式,在终端运行npx eslint src/index.js,此时就可以看到eslint给我们报的错了 其实第一种报错和保存文件时自动修复的功能是刚刚下载的ESLint插件提供的功能,第二种报错是刚刚下载的eslint依赖提供的功能,但是无论是哪种报错方式,其实都会先去读取我们.eslintrc.json中的配置,然后去执行相应的检测和修复,包括后面会讲到其它代码的Lint工具也是一样的道理
  1. 然后,我们需要创建.eslintignore文件,这个文件很简单,它的作用是定义哪些文件或文件夹不参与eslint的检测
node_modules/
dist/
复制代码
  1. 最后,我们需要去完善一下相关的配置文件
.vscode/setting.json

{
  "editor.formatOnSave": true,
+ "editor.codeActionsOnSave": {
+   "source.fixAll.eslint": true
+ },
+ "eslint.validate": [
+   "javascript"
+ ],
}
复制代码

上面配置的意思是在保存代码的时候对javascript文件尝试自动修复eslint错误,我们可以自己尝试一下代码缩进问题的自动修复

package.json

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
+ "eslint": "eslint src/**/*.js",
},
复制代码

这里是增加了一条脚本命令用来替代上面的npx eslint src/index.js,这样我们就不用每次都输入一大串命令了,此时我们只要运行脚本npm run eslint就可以遍历检测src目录下的所有js文件,更加的方便直观

Stylelint - 一个强大的现代linter,可帮助您避免错误并在您的样式中强制执行约定

  1. 首先,我们同样需要下载stylelint和Stylelint插件,在终端执行npm install stylelint stylelint-config-standard(stylelint-config-standard是stylelint的标准规则配置)

  2. 其次,我们需要创建.stylelintrc.json文件

{
  "extends": [
    "stylelint-config-standard"
  ],
  "ignoreFiles": [
    "node_modules/",
    "dist/"
  ],
  "rules": {}
}
复制代码

这里其实和eslint是一样的道理,不同的是stylelint是对css文件做检测的,在这里,我们继承了stylelint-config-standard的标准配置,然后同样也会有一个rules的配置

  • 我们可以创建一个index.css文件,然后写上一个body { width: 0px },这时候就能看到stylelint给我们以红色波浪线的方式报错了,因为标准的配置是有规定0后面不需要有单位的
  • 我们也同样可以通过命令行的方式,在终端运行npx stylelint src/index.css,此时也同样可以看到stylelint给我们报的错了
  1. 最后,我们再去完善一下相关的配置文件
.vscode/setting.json

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
+   "source.fixAll.stylelint": true
  },
  "eslint.validate": [
    "javascript"
  ],
+ "stylelint.validate": [
+   "css"
+ ],
}
复制代码
package.json

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "eslint": "eslint src/**/*.js",
+ "stylelint": "stylelint src/**/*.css",
},
复制代码

上面两个文件的配置相信大家应该也能知道是干什么的了哈

Prettier - 一个“有态度”的代码格式化工具

这里可能有人会问既然我们已经有了editorConfig,eslint,stylelint去统一js和css的风格,为什么还需要prettier呢?这里其实网上有很多种说法,感兴趣可以去网上看一下,简单来说editorConfig是对项目中所有文件的统一编码风格,eslint和stylelint是专门针对与js和css的,它们不但会检测代码格式还会检测代码语法,而prettier是专门针对于代码风格的,而且支持的文件种类也非常的多,只有结合它们四个才能全面的统一项目的编码风格

  1. 首先,我们还是下载prettier(npm install prettier)和Prettier - Code formatter插件

  2. 其次,我们需要创建.prettierrc.json文件

{
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "quoteProps": "as-needed",
  "jsxSingleQuote": true,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "always",
  "requirePragma": false,
  "insertPragma": false,
  "proseWrap": "preserve",
  "htmlWhitespaceSensitivity": "css",
  "endOfLine": "lf",
  "embeddedLanguageFormatting": "auto"
}
复制代码

prettier的配置相对来说比较简单,只有rules的相关配置,大概支持20多种的规则配置,比如"printWidth": 80就是一行超过80个字符就会强制换行

  • 但是在这里需要注意一下prettier和之前的Lint工具不一样的地方,它不会在文件中给我以波浪线的方式提示错误
  • 所以我们只能通过命令行的方式,比如我们可以尝试在任何的文件中写一行超过80个字符的代码,在终端运行npx prettier src/**/* --check,此时就可以看到prettier给我们报的错了
  1. 然后,我们同样需要创建.prettierignore文件
node_modules/
dist/
复制代码
  1. 最后,我们也需要去完善一下相关的配置文件
.vscode/setting.json

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.fixAll.stylelint": true
  },
  "eslint.validate": [
    "javascript"
  ],
  "stylelint.validate": [
    "css"
  ],
+ "[html]": {
+   "editor.defaultFormatter": "esbenp.prettier-vscode"
+ },
+ "[css]": {
+   "editor.defaultFormatter": "esbenp.prettier-vscode"
+ },
+ "[javascript]": {
+   "editor.defaultFormatter": "esbenp.prettier-vscode"
+ },
+ "[typescript]": {
+   "editor.defaultFormatter": "esbenp.prettier-vscode"
+ }
}
复制代码

上面配置的意思是在保存代码的时候对各种类型的文件运行prettier格式化程序

package.json

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "eslint": "eslint src/**/*.js",
+ "prettier": "prettier src/**/* --check",
+ "lint": "npm run eslint && npm run stylelint && npm run prettier",
},
复制代码

这里的脚本命令也是相同的道理,不同的是这里是遍历src目录下的所有文件夹,而且还加了一个lint脚本,就是同时执行刚刚的eslint,stylelint和prettier这三个脚本

完成上面的配置后,保存文件就可以自动格式化了,或者运行脚本命令也可以看到报错信息啦

解决工具间的冲突问题

当我们按照上面的步骤配置好eslint,stylelint和prettier后,肯定会发现有一个严重的问题,没错,就是冲突问题。因为它们之间的功能确是由交集的,比如说代码缩进这个规则其实它们三个都可以配置,那问题来了,如果这三个之间配置了不同的缩进规则,那么到底以那个为准呢?其实在上面的配置文件中,保存文件时运行的格式化程序prettier时最高的,所以最后是以prettier为准,但是这样产生的问题就是其它的工具会一直报错,怎么解决呢?

其实解决的方法也很简单,解决思路就是禁用所有eslint和stylelint与prettier发生冲突的规则把代码风格的规则。我们需要下载两个依赖npm install eslint-config-prettier stylelint-config-prettier,然后修改配置文件如下,这样就能完美的解决冲突问题啦

.eslintrc.json

  "extends": [
    "eslint:recommended",
+   "prettier"
  ],
复制代码
.stylelintrc.json

  "extends": [
    "stylelint-config-standard",
+   "stylelint-config-prettier"
  ],
复制代码

好啦,到此为止,我们就基本上配置好了所有的统一编码风格的工具啦,后面再按需修改相关的配置就ok啦!

5. husky&lint-staged&commitlint - 代码提交前的最终校验

上面我们说到通过好几个工具的配置完成了对我们编码风格的统一。但如果有的人写了一些不符合统一风格的代码而且没有修复就提交了,那该怎么办呢?如果大家都这样那我们上面做的工作好像就失去了意义了,所以我们如何去阻止这个行为呢?其实我们可以从代码提交时去做一系列的校验工作

husky - Git钩子变得容易了🐶呜呜!

这个东西主要是帮助我们在执行git的相关命令时去执行一些钩子

  1. 第一步我们需要下载husky
npm i husky
复制代码
  1. 第二步我们按照官网的教程分别执行以下操作

编辑package.json > prepare脚本并运行一次:

npm set-script prepare "husky install"
npm run prepare
复制代码

这里的prepare的意思是在执行npm install后执行husky install,这里我们先手动运行一次这个命令,执行完成之后项目会创建一个.husky/_文件夹,里面的husky.sh会有一些脚本,这里我们看看就行,不用动它

添加一个hook:

npx husky add .husky/pre-commit "npm test"
git add .husky/pre-commit
复制代码

这里是通过husky添加一个pre-commit的钩子,执行完成之后会多出一个.husky/pre-commit文件,点开它看看这里大概的意思是在执行commit之前会先执行pre-commit里面的npm test

制作一个commit:

git commit -m "Keep calm and commit"
# `npm test` will run every time you commit
复制代码

然后我们提交一次代码,就会在提交之前执行npm test了,如果这里你能看到终端打印出> echo "Error: no test specified" && exit 1,就说明husky配置成功了

最后我们可以把npm test改成npm run lint,这样每次在代码提交之前就会执行lint检查,不符合规范的代码是无法提交的

lint-staged - 针对暂存的git文件运行linter,不要让💩溜进你的代码库!

上面我们通过husky实现了在代码提交之前进行检查,但是在实际的开发过程中,如果我们每次提交都对所有的代码进行检测,那无疑效率是比较低的。所以这时候就需要lint-staged了,它可以帮我们实现在每次提交时只对git暂存区(改动过的代码)进行检测

  1. 第一步我们需要下载lint-staged
npm i lint-staged
复制代码
  1. 第二步我们按照官网的教程分别执行以下操作

编辑package.json:

+ "lint-staged": {
+   "*.{js,ts}": "eslint --fix",
+   "*.css": "stylelint --fix",
+   "*.": "prettier --write"
+ },
复制代码

这里是指定对暂存区的哪些文件执行哪个校验,和之前的lint脚本不同的地方在于这里后面加上了--fix--write,就是在检查时尝试去修复这些错误

编辑.husky/pre-commit:

- npm run test
+ npx lint-staged
复制代码

这里就是把提交之前需要执行的脚本换成npx lint-staged,这样就可以在每次提交之前只对暂存区的文件进行检查了

完成上述配置后我们可以尝试在文件中写一些不符合规范的代码,然后尝试提交lint-staged就会报错,并且会提交失败

commitlint - Lint 提交消息

好了,到这里我们所提交的代码都是符合规范了,那么还剩最后一步,就是提交的信息也要符合规范,否则别人不知道你这次提交是干了什么,这里就需要commitlint了,它是检查您的提交消息是否符合常规提交格式,一般来说,模式大多看起来像这样:(看上去比较复杂,其实很简单,通常都是feat: "XXX"

type(scope?): subject  #scope is optional; multiple scopes are supported (current delimiter options: "/", "\" and ",")
复制代码
  1. 第一步我们需要下载@commitlint/cli@commitlint/config-conventional(commitlint常规配置)
npm i lint-staged
复制代码
  1. 第二步我们按照官网的教程分别执行以下操作

添加一个hook:

cat <<EEE > .husky/commit-msg
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx --no -- commitlint --edit "${1}"
EEE
复制代码

这里是通过husky添加一个commit-msg的钩子,执行完成之后会多出一个.husky/commit-msg文件,点开它看看这里大概的意思是在执行commit之前会先执行commit-msg里面的npx --no -- commitlint --edit "${1}",也就是校验commit消息

  1. 第三步我们需要配置commitlint
.commitlintrc.json

+ {
+   "extends": [
+     "@commitlint/config-conventional"
+   ]
+ }
复制代码

这里和之前不太一样的地方是选哟一个配置文件来配置我们的commit消息需要符合什么样的规范

现在我们可以尝试完成提交一次,并且输入一次错误的提交信息比如featt: "XXX",就看到到终端报错了,然后我们改成正确的提交信息成功提交

到此为止,我们已经完成了代码提交前检验的所有配置,这样提交的所有代码也都是符合规范的了!

favicon.svg 所有的源码都在这里(如果觉得对你有帮助,求star支持,感谢!🙏)

下一篇:第三章《代码编译篇》Browserslist&PostCss&Babel

分类:
前端