开发流程规范 — commit及其之后的阶段

导语：当代码开发完成之后，需要进行的就是 add --> commit --> push，但是为了让代码编写风格更统一、代码逻辑更健壮、提交信息更清晰、变更信息可追溯，就需要做一些必要的检查和约束，本文就是对这些的实践。

整体流程图‍‍

主要是利用 git hooks监听一些关键的 hook 来执行设定的逻辑。

以下具体说明每个步骤需要做什么事情，应该怎么做。

pre-commit-msg：代码风格、测试用例检查

在执行 git commit 后，首先要通过 pre-commit-msg hook 对更改的文件进行代码格式、测试用例检查，这个时机点检查既不会影响开发过程，又能做统一的收敛，性价比很高。如果直接配置 git hooks，会比较麻烦而且不便于多人合作开发，所以这里使用 husky 库设置：

# 安装
npm install husky -D
# 初始化
npm set-script prepare "husky install"
npm run prepare
# 添加 hook，xxx 表示需要添加的命令
npx husky add .husky/pre-commit "xxx"

对代码格式的检查，这里使用的是 eslint 库：

# 安装
npm install eslint -D
# 生成配置文件 .eslintrc.js
npm init @eslint/config

如何配置 eslint 请参考官方文档(或者期待本系列针对 eslint 的文章)。

对代码测试的实践暂未开始，可以主动调研相关的库(或者期待针对本系列针对其的文章)。

设置在 pre-commit hook 时触发 eslint 检查：

npx husky add .husky/pre-commit "npx eslint"
# 自动修复检查出的问题
npx husky add .husky/pre-commit "npx eslint --fix"

上面执行的命令 npx eslint --fix 会检查项目下所有文件，会减慢检查的速度，尤其当项目变大，代码量变多后，其实只要对更改的文件，更准确地说是添加到 暂存区(staged) 的文件进行检查即可。这里使用的是 lint-staged 库来设置：

# 安装
npm i lint-staged -D

然后在 package.json 中进行配置：

# 添加 lint-staged 字段，并指定需要检查的文件和命令
"lint-staged": {
    "*.{ts,tsx}": "npx eslint --fix"
  }

同时更改 pre-commit hook 设置的命令：

npx husky add .husky/pre-commit "npx lint-staged"

prepare-commit-msg hook：commit msg 填写提示

当通过上述的检查之后，就需要填写 commit msg，为了使其规范化，这里使用 Commitizen 和 husky 实现命令行交互提示，只要按照提示来填写就会生成规范化的 commit msg：

# 安装，更推荐本地安装
npm install commitizen -D
# 初始化
npx commitizen init cz-conventional-changelog --save-dev --save-exact

上面初始化命令使用的是 cz-conventional-changelog adapter，此 adapter 遵循的 commit msg 规范是 Conventional Commits，不同 adapter 依据不同的 commit msg 规范并且可能有不同的展示形式，可以选择适合项目的 adapter。

执行命令后会在 package.json 中添加：‍‍‍

"config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  },

再设置在 prepare-commit-msg hook 时触发命令行交互提示：

# Commitizen 官方文档上写的是 exec < /dev/tty && npx cz --hook || true，这是错误的
# 详情请查看相关 issue：https://github.com/commitizen/cz-cli/issues/809
npx husky add .husky/prepare-commit-msg "exec < /dev/tty && npx git-cz --hook || true"

commit-msg hook：commit msg 检查

填写完 commit msg 后，还需要检查符不符合设定的格式，主要防止绕过上述 commit msg 填写提示流程的场景。这里使用 commitlint 库 和 husky 设置：

# 安装
npm install @commitlint/{config-conventional,cli} -D
# 创建配置文件并写入文件
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

配置文件 commitlint.config.js 中使用的扩展是 @commitlint/config-conventional，也是遵循 Conventional Commits。可以根据项目遵循的 commit msg 规范选择合适的扩展。

再设置 commit-msg hook 时触发 commit msg 检查：

npx husky add .husky/commit-msg "npx --no -- commitlint --edit "$1""

更新版本号/生成 changelog 信息

在 library 或者业务项目的开发过程中，对于一些新增特性或者修复 bugs 后更新 package.json 中的版本号，并且生成 changelog 信息是非常重要的，这样能保留开发的历史记录，便于追溯。

这里需要注意的是，更新版本号和生成 changelog 信息这个过程会变更文件，所以还需要再次 git commit 。这里使用 stardard-version 来设置，它会自动提交由此变更的文件：

# 安装
npm i standard-version -D

在 package.json 中 script 添加：

# HUSKY=0 的作用是禁止掉所有之前设置的 git hooks 检查，不然会导致 commit 失败
# 详情请看相关 issue：https://github.com/commitizen/cz-cli/issues/631
"release": "HUSKY=0 standard-version"

最后

关于上述文章所提及的库和名词，更详细的信息请查看：

git hooks 文档 https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks

husky 文档 https://github.com/typicode/husky

eslint 文档 https://eslint.org/docs/user-guide/getting-started

lint-staged 文档 https://github.com/okonet/lint-staged

Commitizen 文档 https://github.com/commitizen/cz-cli

cz-conventional-changelog adapter 文档 https://www.npmjs.com/package/cz-conventional-changelog

Conventional Commits 规范 https://www.conventionalcommits.org/en/v1.0.0/

commitlint 文档 https://github.com/conventional-changelog/commitlint

@commitlint/config-conventional 文档 https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional

standard-version 文档 https://github.com/conventional-changelog/standard-version

上述文章表述或者在实践中有任何问题，欢迎联系我。

注意：本文章只是 开发流程规范 的其中一篇，本系列致力于记录如何构建规范化的开发流程以及实践。