标准化大厂编程规范解决方案之ESLint + prettier + Git Hooks

一江东流水
485 阅读8分钟

一起养成写作习惯！这是我参与「掘金日新计划 · 4 月更文挑战」的第24天，点击查看活动详情。

编码规范

ESLint

ESLint 是 2013年6月 创建的一个开源项目，它的目标非常简单，只有一个，那就是 提供一个插件化的 javascript 代码检测工具 ，说白了就是做 代码格式检测使用的

在项目中，包含一个 .eslintrc.js 文件，这个文件就是 eslint 的配置文件。

我们在创建项目时，就进行过这样的选择：

? Pick a linter / formatter config: 
  ESLint with error prevention only // 仅包含错误的 ESLint
  ESLint + Airbnb config // Airbnb 的 ESLint 延伸规则
  ESLint + Standard config // 标准的 ESLint 规则

当前选择了 标准的 ESLint 规则 ，看一看 ESLint 它的一些配置都有什么？

// ESLint 配置文件遵循 commonJS 的导出规则，所导出的对象就是 ESLint 的配置对象
module.exports = {
  // 表示当前目录即为根目录，ESLint 规则将被限制到该目录下
  root: true,
  // env 表示启用 ESLint 检测的环境
  env: {
    // 在 node 环境下启动 ESLint 检测
    node: true
  },
  // ESLint 中基础配置需要继承的配置
  // plugin:vue/vue3-essential对vue3语法的配置
  // @vue/standard对vue语法的基本配置
  extends: ["plugin:vue/vue3-essential", "@vue/standard"],
  // 解析器
  parserOptions: {
    parser: "babel-eslint"
  },
  // 需要修改的启用规则及其各自的错误级别
  /**
   * 错误级别分为三种：
   * "off" 或 0 - 关闭规则
   * "warn" 或 1 - 开启规则，使用警告级别的错误：warn (不会导致程序退出)
   * "error" 或 2 - 开启规则，使用错误级别的错误：error (当被触发的时候，程序会退出)
   */
  rules: {
    "no-console": process.env.NODE_ENV === "production" ? "warn" : "off",
    "no-debugger": process.env.NODE_ENV === "production" ? "warn" : "off"
  }
};

试想一下，在你去完成项目代码的同时，还需要时时刻刻注意代码的格式问题，这将是一件多么痛苦的事情！

那么有没有什么办法，既可以保证 ESLint 规则校验，又可以解决严苛的格式规则导致的影响项目进度的问题呢？答案是prettier

ESLint 与 Prettier 配合解决代码格式问题

  1. 在 VSCode 中安装 prettier 插件
  2. 在项目中新建 .prettierrc 文件，该文件为 perttier 默认配置文件
  3. 在该文件中写入如下配置：
{
  // 不尾随分号
  "semi": false,
  // 使用单引号
  "singleQuote": true,
  // 多行逗号分割的语法中，最后一行不加逗号
  "trailingComma": "none"
}
  1. 打开vscode的配置 -> format on save设置为true 至此，你即可在 VSCode 保存时，自动格式化代码！

但是！  你只做到这样还不够！

  • 如果大家的 VSCode 安装了多个代码格式化工具的，需要把prettier设置为默认格式化工具，利用prettier这个工具去格式化代码
  • ESLint 和 prettier 之间的冲突问题。如果格式产生冲突，要么修改eslint的规则，要么修改prettier的规则。

至此我们整个的 perttier 和 ESLint 的配合使用就算是全部完成了。在之后我们写代码的过程中，只需要保存代码，那么 perttier 就会帮助我们自动格式化代码，使其符合 ESLint 的校验规则。而无需我们手动进行更改了。

git 提交规范

通常情况下，我们都会通过 git 来管理项目。只要通过 git 来管理项目，那么就必然会遇到使用 git 提交代码的场景。

当我们执行 git commit -m "描述信息" 的时候，我们知道此时必须添加一个描述信息。但是中华文化博大精深，不同的人去填写描述信息的时候，都会根据自己的理解来进行描述。

而很多人的描述 “天马行空” ，这样就会导致别人在看你的提交记录时，看不懂你说的什么意思？不知道你当前的这次提交到底做了什么事情？会不会存在潜在的风险？

所以 git 提交规范 势在必行。

约定式提交

以目前使用较多的Angular团队规范延伸出的 Conventional Commits specification（约定式提交） 为例，来为大家详解 git 提交规范

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

--------  翻译 -------------

<类型>[可选 范围]: <描述>

[可选 正文]

[可选 脚注]

其中 <type> 类型，必须是一个可选的值，比如：

  1. 新功能：feat
  2. 修复：fix
  3. 文档变更：docs
  4. .... 你的一次提交描述应该式这个样子的： image.png

但是这样太麻烦了，要是每次都这么写，写到猴年马月了！

Commitizen

如果严格安装 约定式提交规范， 来手动进行代码提交的话，那么是一件非常痛苦的事情，于是就出现了一种叫做 git 提交规范化工具 的东西，其中的 commitizen 就是其中的佼佼者！

commitizen 仓库名为 cz-cli ，它提供了一个 git cz 的指令用于代替 git commit，简单一句话介绍它：

当你使用 commitizen 进行代码提交（git commit）时，commitizen 会提交你在提交时填写所有必需的提交字段

  1. 全局安装Commitizen
npm install -g commitizen@4.2.4
  1. 安装并配置 cz-customizable 插件
npm i cz-customizable@6.3.0 --save-dev
// 添加以下配置到 `package.json `中
"config": {
    "commitizen": {
      "path": "node_modules/cz-customizable"
    }
  }
  1. 项目根目录下创建 .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: 72
    }
  1. 使用 git cz 代替 git commit 使用 git cz 代替 git commit，即可看到提示内容。

现在可以使用git cz 来代替了 git commit 实现了规范化的提交诉求了，但是当前依然存在着一个问题，那就是我们必须要通过 git cz 指令才可以完成规范化提交！那么如果有马虎的同事，它们忘记了使用 git cz 指令，直接就提交了怎么办呢？

Git Hooks

Git hooks（git 钩子 || git 回调方法）也就是：git 在执行某个事件之前或之后进行一些其他额外的操作。

而我们所期望的 阻止不合规的提交消息，那么就需要使用到 hooks 的钩子函数。整体的 hooks 非常多，当时我们其中用的比较多的其实只有两个：

Git Hook调用时机说明
pre-commitgit commit执行前 它不接受任何参数，并且在获取提交日志消息并进行提交之前被调用。脚本git commit以非零状态退出会导致命令在创建提交之前中止。可以用git commit --no-verify绕过
commit-msggit commit执行前 可用于将消息规范化为某种项目标准格式。 还可用于在检查消息文件后拒绝提交。可以用git commit --no-verify绕过

简单来说这两个钩子：

  1. commit-msg：可以用来规范化标准格式，并且可以按需指定是否要拒绝本次提交
  2. pre-commit：会在提交前被调用，并且可以按需指定是否要拒绝本次提交

使用 husky + commitlint 检查提交描述是否符合规范要求

了解了 git hooks 的概念，那么接下来我们就使用 git hooks 来去校验我们的提交信息。 要完成这么个目标，那么我们需要使用两个工具：

  1. commitlint：用于检查提交信息
  2. husky：是git hooks工具

commitlint

  1. 安装依赖：
npm install --save-dev @commitlint/config-conventional@12.1.4 @commitlint/cli@12.1.4
  1. 创建 commitlint.config.js 文件，增加配置项
module.exports = {
  // 继承的规则
  extends: ['@commitlint/config-conventional'],
  // 定义规则类型
  rules: {
    // type 类型定义，表示 git 提交的 type 必须在以下类型范围内
    'type-enum': [
    // 验证的错误级别
      2,
    // 什么情况下进行验证
      'always',
      [
        'feat', // 新功能 feature
        'fix', // 修复 bug
        'docs', // 文档注释
        'style', // 代码格式(不影响代码运行的变动)
        'refactor', // 重构(既不增加新功能，也不是修复bug)
        'perf', // 性能优化
        'test', // 增加测试
        'chore', // 构建过程或辅助工具的变动
        'revert', // 回退
        'build' // 打包
      ]
    ],
    // subject 大小写不做校验
    'subject-case': [0]
  }
}

husky

  1. 安装依赖：
npm install husky@7.0.1 --save-dev
  1. 启动 hooks ， 生成 .husky 文件夹
  2. 在 package.json 中生成 prepare 指令
scripts: {
    "prepare": "husky install"
}
  1. 执行 prepare 指令: npm run prepare
  2. 添加 commitlint 的 hook 到 husky中，并指令在 commit-msg 的 hooks 下执行 npx --no-install commitlint --edit "$1" 指令。此时的 .husky 的文件结构如下：

image.png

至此， 不符合规范的 commit 将不再可提交：

PS F:\xxxxxxxxxxxxxxxxxxxxx\imooc-admin> git commit -m "测试"
⧗   input: 测试
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky - commit-msg hook exited with code 1 (error)

我们就已经可以处理好了 强制规范化的提交要求，到现在 不符合规范的提交信息，将不可在被提交！

通过 pre-commit 检测提交时代码规范

如果有人没有用eslint+prettirer处理语法格式，直接提交了怎么办？所以我们就需要有一种方式来规避这种风险。

那么想要完成这么一个操作就需要使用 husky 配合 eslint 才可以实现。我们期望通过 husky 监测 pre-commit 钩子，在该钩子下执行 npx eslint --ext .js,.vue src 指令来去进行相关检测：

  1. 执行 npx husky add .husky/pre-commit "npx eslint --ext .js,.vue src" 添加 commit 时的 hook （npx eslint --ext .js,.vue src 会在执行到该 hook 时运行）
  2. 该操作会生成对应文件 pre-commit

image.png 3. 改动一行代码，使其不符合 ESLint 校验规则，执行 提交操作 会发现，抛出一系列的错误，代码无法提交。

lint-staged 自动修复格式错误

我们通过 pre-commit 处理了 检测代码的提交规范问题，当我们进行代码提交时，会检测所有的代码格式规范 。

但是这样会存在两个问题：

  1. 我们只修改了个别的文件，没有必要检测所有的文件代码格式
  2. 它只能给我们提示出对应的错误，我们还需要手动的进行代码修改

那么想要处理这两个问题，就需要使用另外一个插件 lint-staged ！

lint-staged 可以让你当前的代码检查 只检查本次修改更新的代码，并在出现错误的时候，自动修复并且推送。lint-staged无需单独安装，我们生成项目时，vue-cli 已经帮助我们安装过了，所以我们直接使用就可以了。

  1. 修改 package.json 配置
"lint-staged": {
    "src/**/*.{js,vue}": [
      "eslint --fix",
      "git add"
    ]
  }

  1. 如上配置，每次它只会在你本地 commit 之前，校验你提交的内容是否符合你本地配置的 eslint规则，校验会出现两种结果： 1）. 如果符合规则：则会提交成功。 2）. 如果不符合规则：它会自动执行 eslint --fix 尝试帮你自动修复，如果修复成功则会帮你把修复好的代码提交，如果失败，则会提示你错误，让你修好这个错误之后才能允许你提交代码。

  2. 修改 .husky/pre-commit 文件

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx lint-staged
  1. 再次执行提交代码，发现 暂存区中 不符合 ESlint 的内容，被自动修复

总结

编程格式规范的问题，整个规范大体可以分为两大类：

  1. 代码格式规范
  2. git 提交规范

对于 代码格式规范 而言，我们通过 ESLint + Prettier + VSCode 配置 配合进行了处理。

对于 git 提交规范 而言我们使用了 husky 来监测 Git hooks 钩子，并且通过以下插件完成了对应的配置：

  1. 约定式提交规范
  2. commitizen：git 提交规范化工具
  3. commitlint：用于检查提交信息
  4. commit-msg pre-commit： git hooks 钩子
  5. lint-staged：只检查本次修改更新的代码，并在出现错误的时候，自动修复并且推送。
avatar
文章
阅读
粉丝