郭郭的博客
如何通过自动化流程保证前端代码质量
2023-09-24
前端工程化
00
请注意，本文编写于 812 天前，最后修改于 0 天前，其中某些信息可能已经过时。

目录

glob模式匹配
基本用法
类比正则表达式
.gitignore 扩充的规则
EditorConfig
Prettier
Prettier规则
配置VSCode插件
类比eslint，看看它的功能
Eslint
ESLint 是否可替代 Prettier
ESlint和Pretter的综合案例
Stylelint
StyleLint基本功能
VSCode编辑器配置
融合Prettier
Git Hook背景
husky
commitlint
lint-staged仅校验本次提交
综合案例
VSCode推荐插件

本文系统梳理前端代码规范，包含以下内容

  1. glob语法（它在前端工程化领域用途很广）
  2. prettier格式化工具
  3. stylelint样式检查工具
  4. eslintJS检查工具
  5. prettier + stylelint + eslint 的融合使用及VSCode配置
  6. husky + lint-staged commit前对按需检查，commitlint对注释检查
  7. 一个综合案例， 集成了CICD 。

glob模式匹配

为什么要说 glob模式匹配 呢，因为本文涉及的代码规范工具如EditorConfig、Eslint、Prettier的配置有它的身影。实际上应该是所有工具只要涉及文件匹配的都是使用它，比如.gitignore、webpack.config.js、 gulpfile.js、 tsconfig.json等。

它与正则表达式用途有本质区别，正则表达式适用更广泛，它只处理文件匹配。因为它的规则更少。

背景：

  1. 它最初是贝尔实验室 Unix 系统上的一个名叫 glob 的命令（glob 是 global 的缩写），用于展开命令行中的通配符。
  2. 后来系统提供了该功能的 C 语言库函数glob()，知名的 shell 解释器就使用了该接口，shell 脚本和命令行中使用的 glob 模式匹配功能便源自于此。

基本用法

规则 示例 匹配 不匹配
?匹配单个字符
匹配多个字符用多个?		 ls ?.txt a.txt、b.txt aa.txt、.txt
*表示任意数量的字符 ls a*.txt a.txt、ab.txt b.txt、bb.txt
[...]匹配方括号之中的任意一个字符 ls [ab].txt a.txt、b.txt c.txt
[start-end]表示一个连续的范围 ls [a-c].txt a.txt、b.txt、c.txt d.txt
[^...]不在方括号里面的字符
[!...]与[^...]作用完全一样		 ls [^a].txt b.txt、c.txt a.txt
ls [^a-c].txt d.txt a.txt、b.txt、c.txt
{...}表示匹配大括号里面的所有模式，模式之间使用逗号分隔。 echo d{a,e}g dag、deg dog
它可以用于多字符的模式。
echo {cat,dog}		 cat、dog dag
{start..end}会匹配连续范围的字符。 echo d{a..c}g dag、dbgdcg ddg
匹配a文件夹下任意txt文件 ls a/*.txt a/b.txt、a/cc.txt -
深度匹配当前文件夹下任意文件 ls **/* f1/f1.txt、f1/f2.txt、f2/b.s、f2/txt、f1/ff/ff1.txt -
{start..end}会匹配连续范围的字符。 echo d{a..c}g dag、dbgdcg ddg

更多{...}模式

image.png

更多{start..end}模式

image.png

那么在前端工程化中如何使用glob模式匹配呢？

可使用 node-glob ，它基于 minimatch 和 Node 实现 glob 模式遍历文件的 API。

类比正则表达式

  • glob 模式主要用于匹配文件路径
  • 当然也可以用于匹配字符串，不过在匹配字符串的能力上比 regexp 要弱很多。

image.png

.gitignore 扩充的规则

  • 所有空行或者以 # 开头的行都会被 Git 忽略
  • 匹配模式可以以 / 开头防止递归
  • 匹配模式可以以 / 结尾指定目录
  • 要忽略指定模式以外的文件或目录，可以在模式前加上惊叹号 ! 取反

参考资料：

EditorConfig

官网

  • EditorConfig是用于多人协作使用同编辑器和IDE时，能够保持统一的代码风格
  • 它作用于代码书写和预览阶段
  • 它可以作用于任何文件（通过配置文件制定哪些文件使用哪些规则）
  • 一些重量级工具如webstorm内置了EditorConfig， 一些轻量级工具如VSCode、Subline Text 需要安装插件

EditorConfig的匹配非常少，以下是个人推荐的配置示例

ini
# 已经是顶层配置文件，不必继续向上搜索
root = true

# 所有文件都必须遵守的规则
[*]
# 编码字符集
charset = utf-8
# 缩进风格是空格
indent_style = space
# 一个缩进占用两个空格，因没有设置tab_with，一个Tab占用2列
indent_size = 2
# 换行符 lf
end_of_line = lf
# 文件以一个空白行结尾
insert_final_newline = true
# 去除行首的任意空白字符
trim_trailing_whitespace = false

# md文件要准守的规则
[*.md]
insert_final_newline = false
trim_trailing_whitespace = false

注意

  • 这里面的文件匹配使用的就是 glob模式匹配
  • 后面介绍的Prettier 和 Eslint等工具的配置文件也是 glob模式匹配 ，后续不在强调

Prettier

  • Prettier是一个固执己见的代码格式化工具，固执己见是指它只有少量选择，它内置了一些规则（无需在代码审查中讨论风格，节省您的时间和精力）
  • 它默认支持 js/ts/css/yml/html/md 文件， 其他文件想要支持的话要使用插件
  • 它只关注代码风格， 不关注代码质量（一些低级错误，如使用未定义的变量）问题。
  • 它作用于输入和预览阶段

Prettier规则

看一下Prettier的配置示例

  • .prettierrc.json
json
{
  "printWidth": "100",
  "tabWidth": 4,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "quoteProps": "as-needed",
  "jsxSingleQuote": true,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "jsxBracketSameLine": false,
  "arrowParens": "always",
  "insertPragma": true,
  "proseWrap": "preserve",
  "vueIndentScriptAndStyle": false,
  "endOfLine": "lf",
  "embeddedLanguageFormatting": "auto",
  "singleAttributePerLine": false
}

Prettier的配置文件有有很多种方式

image.png

关于每个配置项的作用建议前往官网查看（虽然是英文文档，但是有图示一看便懂）

它和EditorConfig有一些功能重叠，但是EditorConfig配置极少， 只要保证endOfLine、useTabs、tabWidth两者一致即可。

还有一点区别是EditorConfig可以作用域所有类型的文件，Prettier作用的文件类型有限

配置VSCode插件

  1. 在VSCode中使用Prettier需要安装插件， --略
  2. 配置VSCode支持使用Prettier为格式化

image.png

image.png

这时候会在你的项目文件夹下生成.vscode/settings.json文件

image.png

这样Command + S 保存就可以使用Prettier自动格式化代码了。

默认只是CSS/JS/HTML/TS文件会使用Prettier格式化， 如果是JSX/TSX/vue文件还需要一步额外操作

image.png

image.png

image.png

类比eslint，看看它的功能

-Prettiereslint
功能只关注代码风格关注代码风格和代码质量
作用时机作用于输入和预览阶段作用于保存阶段
CLInpx prettier --write .
prettier . "!**/*.{js,jsx,vue}" --write		npx eslint --fix .
配置文件支持JSON/JS格式支持JSON/JS/YAML格式
API方式使用支持支持
忽略文件.prettierignore.eslintignore
禁止区块<!-- prettier-ignore-start -->
<!-- prettier-ignore-end -->		/*eslint-disable*/
/*eslint-enable*/
禁止单行// prettier-ignore
<!-- prettier-ignore -->		// eslint disable
// eslint-disable-line no-var
/* eslint-disable no-var,space-before-function-paren */

Eslint

关于eslint之前单独写过一篇文章《Eslint深入浅出》

ESLint 是否可替代 Prettier

由于Eslint功能包含代码风格和代码质量，而Prettier仅关注代码风格，那么 ESLint 是否可替代 Prettier ?

有以下两点无法取代Prettier

  1. ESLint中的Formatting rules并非都提供了fixer
  2. ESLint着重于 JS/TS 无法兼容CSS/Markdown/Html 术业有专攻，代码规范方面得交给Prettier

既然不能替代，那么两者之间怎么解决冲突？

eslint-plugin-prettier插件增加了prettier/prettier规则，该规则执行prettier并将错误信息上报eslint。简言之，把prettier融合到eslint中，担负起代码检查的功能，同时需要配合搭配eslint-config-prettier关闭调ESLint中代码风格相关的规则。

ESlint和Pretter的综合案例

我尝试写了一个支持前端各种类型（JS/CSS/SCSS/HTML/TS/JSX/TSX）的文件编辑器提示和格式化的脚手架Demo

  • .editorconfig配置不变，见前面的模板
  • .prettierrc.json 配置不变，见前面的模版
  • ..eslintrc.js 内容如下
js
module.exports = {
  env: {
    browser: true,
    es2021: true,
  },
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:vue/vue3-essential",
    "prettier",
  ],
  overrides: [
    {
      env: {
        node: true,
      },
      files: [".eslintrc.{js,cjs}"],
      parserOptions: {
        sourceType: "script",
      },
    },
  ],
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaVersion: "latest",
    sourceType: "module",
  },
  plugins: ["vue", "prettier"],
  rules: {
    'prettier/prettier': 'error',
  },
}

该配置做了以下事情

  1. 支持了TS/JSX/TSX/Vue格式的文件
  2. 将Prettier融入Eslint，代码风格交给Prettier处理

有些项目不一定使用Prettier，所以还需要研究了下VSCode中使用Eslint自动格式化, 配置方法与前面Prettier格式化类似

image.png

总结

  1. Eslint只能格式化 JS/TS/JSX/TSX 文件
  2. 其他类型文见CSS/SCSS/HTML/Vue等还是需要使用Prettier进行格式化
  3. VSCode需要安装Prettier、ESlint、Volar插件(Volar是vue3语法的插件)

再次注意: 上述案例有个坑，你会发现使用eslint格式化快捷键，Prettier的规则没有生效。
但是如果使用npx eslint --fix和npx prettier --write格式化同一个文件发现结果一样，说明项目配置没问题。
格式化的文件发现eslint的提示并不对，这说明是 VSCode的ESlint插件问题，翻了很多文档，坑了我几个小时， 终于找到答案, 调整配置如下

image.png

这样就可以愉快的玩耍了（其实还有点小问题，由于CommonJS模块的缓存行， 修改Prettier配置需要重新使用VSCode打开项目，但是规范制定好，只要不去改规范就没不会遇到问题）。

本段落完整代码点这里

Stylelint

stylelint 可以类比 eslint 在JS中的作用，它不仅管代码风格还管代码质量

先贴出 官网 官方在线demo 以下内容来自官方介绍

它将帮助您避免错误，例如：

  • 无效的东西，例如定义了grid-area的无效值
  • 有疑问的东西，例如重复选择器
  • 有问题的东西，例如属性名称拼写错误

并强制执行约定，例如：

  • 禁止某些规则，例如具体某个单位
  • 强制命名模式，例如对于自定义属性采用短横线kebab-case规范
  • 设定限制，例如ID选择器的数量
  • 指定符号，例如现代色彩函数

我们建议使用像 Prettier 和 Stylelint。 Linters 和 Prettier是互补的工具，它们一起工作可以帮助您编写一致且无错误的代码。

贴一张图解释前面的描述

image.png

StyleLint基本功能

这里先简单总结一下它的功能，有大致的了解。

  1. 配置文件
    配置文件有多种形式，按以下优先级顺序
  • package.json中的stylelint
  • .stylelintrc文件 JSON格式
  • .stylelintrc.{cjs,js,json,yaml,yml} file
  • stylelint.config.{cjs,mjs,js} file
  1. rules规则
json
{
  "rules": {
    "color-no-invalid-hex": true
  }
}

值类型有以下几种

  • null 关闭规则
  • 单个值 主要选项
  • 数组形式 [主要选项, 次要选项]
  • 许多规则提供了用于进一步定制的辅助选项。要设置辅助选项，请使用双成员数组。例如
json
{
  "rules": {
    "selector-pseudo-class-no-unknown": [
      true,
      {
        "ignorePseudoClasses": ["global"]
      }
    ]
  }
}
  1. 命令行使用

前面的案例执行效果如下图 image.png

  1. 特殊处理
  • 默认屏蔽文件 .stylelintignore 这里也是glob语法
  • 区块屏蔽、条件屏蔽等与eslint非常像
css
/* stylelint-disable */
区块屏蔽
/* stylelint-enable */

/* stylelint-disable declaration-no-important */
区块屏蔽
/* stylelint-enable declaration-no-important */

#id {
  /* stylelint-disable-line */
  color: pink !important;
}
/* ...... */

  1. 支持手动编程 参考官网 Node.js API

  2. 支持插件、支持PostCSS插件

VSCode编辑器配置

插件安装不用说了，

按照官方文档写demo，但是没有效果， 坑！折腾了会回找到原因

stylelint-wont-mark-errors-in-vscode

这里贴一下我的配置

  • .vscode/setting.json
json
{
    "editor.formatOnPaste": true,
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      // 文件保存时开启stylelint自动修复程序
      "source.fixAll.stylelint": true
    },
     // 防止编辑器内置linter与插件冲突设置
    "css.validate": false,
    "less.validate": false,
    "scss.validate": false,
    // 启用stylelint插件
    "stylelint.enable": true,
    "stylelint.config": null,
}
  • .stylelintrc.json
json
{
  "extends": [
    "stylelint-config-standard"
  ],
  "rules": {
    "declaration-empty-line-before": "never",
    "unit-allowed-list": [
      "em",
      "rem"
    ],
    "selector-max-id": 1
  }
}

完整代码点这里

融合Prettier

stylelint从15版本起（目前最新版本15.0.3）废弃了 所有与代码风格（Prettier干的事情）的配置，专注于CSS的代码质量。

这里是官方的解释

已弃用的风格规则
我们已经废弃了 76 条强制执行风格约定的规则，例如缩进。

当我们创建这些规则时，Prettier还不存在。他们现在提供了一种更好的方法来一致地格式化代码，尤其是空格。 Linters 和Prettier是互补的工具，它们一起工作可以帮助您编写一致且无错误的代码。

通过弃用这些规则，我们可以：

  • 专注于编写和维护规则，帮助您避免错误并强制执行（非风格）约定，这两者都是 stylelint 所独有的
  • 使我们的代码库现代化，例如迁移到 ESM，以便我们可以更新依赖项并确保 stylelint 的安全

如果你用的stylelint< 14 可以参考这篇文章的配置。

这里 我写了一个案例 stylelint + scss + prettier

Git Hook背景

首先Git支持 自定义钩子 自定义钩子文档 在.git/hooks/这个目录下面

image.png 移除sample就可以使用

但实际上并没有这样用的，我推测有以下几点原因

  1. .git文件夹存在于本地，不会提交到远程仓库，你需要写脚本，脚本是使用shell和Perl语言编写，此外shell脚本在window电脑和mac电脑有一些区别。
  2. 如果格式化失败需要恢复之前的代码
  3. 每次commit做全量检查不友好，需要增量检查

husky

官网

husky 是一个 Git Hook 工具。husky 其实就是一个为 git 客户端增加 hook 的工具。

husky 有一个快捷命令npx husky-init，一键安装并配置pre-commit hook，它会自动完成以下操作

  1. npm pkg set scripts.prepare="husky install"
    • 这里在package.json文件中增加了一个script脚本
  2. npm run prepare
    • prepare是一个钩子，会在npm install、npm publish、npm pack命令前执行 ，详见官网介绍
    • 其他小伙伴在开发前肯定要执行npm install命令， 触发 npm run prepare, 再触发 husky install，
    • husky 会设置.hasky/为git hooks目录
  3. 为了方便，提供了一个pre-commit的默认脚本

你也可以通过node_modules/husky/README.md查看 husky的使用

commitlint

官网

commitlint 是约束git提交代码时注释的规范。

官方的一张图胜过千言万语 commitlint.svg

使用步骤

  1. 安装依赖 pnpm install --save-dev @commitlint/cli @commitlint/config-conventional
  2. 创建配置文件，写入内容 echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
  3. 使用 npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1}'

这样就配置完成了， 当执行git commit -m 'XXX'时就会拦截校验你的XXX内容。

如果你提交没有通过， 会提示你怎么写注释， 这里是文档

你还可以自定义规则

lint-staged仅校验本次提交

使用步骤

  1. 安装 pnpm install -D lint-staged
  2. 修改 husky pre-commit 钩子执行脚本
  • .husky/pre-commit
sh
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged # 校验
  1. 修改 package.json
json
"lint-staged": {
  "src/**/*.{js,ts,vue}": "npx eslint",
  "src/**/*.{css,scss,html,vue}": "npx stylelint --allow-empty-input"
}

本段落完整代码案例点这里

参考资料

综合案例

我写了一个综合案例 github仓库CICD-demo

  • webpack + ts 开发的脚手架
  • 集成jest单元测试
  • 代码规范方案 prettier + stylelint + eslint
  • VScode编辑器支持 prettier + stylelint + eslint
  • husky + lint-staged 提交前对代码按需进行eslint+stylelint校验，对注释进行校验commitlint
  • CICD集成

我们先从package.json梳理流程

json
{
  "script": {
    "lint": "eslint --ext .js,.ts --quiet src --fix && npx lint-staged",
  },
  "pre-commit": [
    "lint"
  ],
  "lint-staged": {
    "*.{css,scss,html,md, vue}": [
      "prettier --write"
    ],
    "*.{css,scss}": [
      "stylelint \"**/*.{css,scss}\""
    ],
    "*.{js,ts}": [
      "jest --bail --passWithNoTests --findRelatedTests"
    ]
  }
}
  1. pre-commit是入口，它是git hooks的钩子，在代码提交前检查代码是否符合规范，不符合规范将不可被提交 这里配置了lint 意思是执行 npm run lint
  2. npm run lint 找到 pkg.script.lint对应的命令eslint --ext .js,.ts --quiet src --fix && npx lint-staged
    • eslint --ext .js,.ts --quiet src --fix 使用eslint格式化src文件夹下面所有后缀为.js、.ts的文件，
      • --quiet仅报告错误，
      • --fix 自动修复， 当然有些错误如运行时错误是无法自动修复的，失败就退出了， 成功继续执行
    • 执行npx lint-staged 会读取配置即pkg.lint-staged
  3. lint-staged 配置了3条规则
    • 使用prettier对项目中所有后缀为.css、.scss、.md、.html的文件进行格式化
    • 使用jest对项目中所有后缀为.spec.js、.spec.ts的文件进行单元测试
      • --bail 执行过程中只要遇到一次错误就退出
      • --passWithNoTests 因为jest默认将没有一个测试用例执行视为错误， 这里告诉jest是正常情况
      • --findRelatedTests 只对有改动的文件进行单元测试

网上也有方案将 eslint格式化配置到 lint-staged里面，这样会遇到一个问题 image.png 所以把eslint放到了外部

VSCode推荐插件

最后推荐一些比较实用的vscode插件

  1. es6-string-html

注： 右边为安装插件后的效果

  1. JavaScript (ES6) code snippets 提供了一些快捷输入的方式比如
  • clg回车 => console.log(object);
  • imp回车 => import moduleName from 'module'
  • edf回车 => export default function test(params) {}
  • 更多请看插件文档

  1. live-server 会本地启动一个服务，选中html文件右击在浏览器打开

  2. Vue Language Features (Volar) vue3语法插件， vue2使用的是Vetur

  3. Compare Folders 文件夹比较

  4. Color Picker 展示颜色

  5. GitLens

本文作者:郭敬文

本文链接:

版权声明:本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！