前端基建必备技能：代码提交规范

前端项目的提交规范是前端基建必备技能之一。下面介绍规范提交代码时会用到的工具，以及在常见场景中如何去使用。

Husky

Git hooks 管理工具。

允许开发者在项目中设置自定义的 Git 钩子脚本。

自动检查您的提交消息、代码，并在提交或推送时运行测试。

安装

npm install --save-dev husky

初始化

npx husky init

初始化成功之后，会在项目根目录下创建.husky和.husky/_文件夹，并创建钩子(git hooks)脚本，目录结构如下：

├─ .husky
│  ├─ _
│  │  ├─ .gitignore
│  │  ├─ applypatch-msg
│  │  ├─ commit-msg
│  │  ├─ h
│  │  ├─ husky.sh
│  │  ├─ post-applypatch
│  │  ├─ post-checkout
│  │  ├─ post-commit
│  │  ├─ post-merge
│  │  ├─ post-rewrite
│  │  ├─ pre-applypatch
│  │  ├─ pre-auto-gc
│  │  ├─ pre-commit
│  │  ├─ pre-push
│  │  ├─ pre-rebase
│  │  └─ prepare-commit-msg
│  └─ pre-commit

Git Hooks

Commitlint

用于验证 Git 提交消息格式是否符合预定义规范的工具，结合 Husky 工具来设置 commit-msg 钩子。

安装

@commitlint/config-conventional 是一个预定义的配置包，与 @commitlint/cli 配合使用来验证 Git 提交消息格式是否符合 Conventional Commits 规范。

npm install --save-dev @commitlint/cli @commitlint/config-conventional

配置

在根目录下创建commitlint.config.js，并配置：

// commit-lint config
module.exports = {
    extends: ['@commitlint/config-conventional'],
    rules: {
      'type-enum': [
        2,
        'always',
        ['build', 'chore', 'ci', 'docs', 'feat', 'fix', 'perf', 'refactor', 'revert', 'style', 'test', 'types'],
      ],
    },
  };
  

常用配置Api

Conventional Commits

约定式提交规范是一种基于提交信息的轻量级约定。

它提供了一组简单规则来创建清晰的提交历史，这更有利于编写自动化工具。

提交说明的结构

<type>[optional scope]: <description> // <类型>[可选 范围]: <描述>

[optional body] // [可选 正文]

[optional footer(s)] // [可选 脚注]

常用类型

常用提交结构示例

// 包含了描述并且脚注中有破坏性变更的提交说明
feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

// 包含了 ! 字符以提醒注意破坏性变更的提交说明
feat!: send an email to the customer when a product is shipped

// 包含范围的提交说明
feat(lang): add polish language

Commitizen

Commitizen 是一个开源的命令行工具，旨在帮助前端（以及所有使用 Git 的项目）开发者遵循一种标准化的提交消息格式。这种规范化提交信息的方式对于维护项目的提交历史、自动化生成 CHANGELOG、以及配合持续集成流程等具有重要作用。

安装

npm install -g commitizen

配置

"scripts": {
    "commit": "cz"
}

执行

git cz
// or
git commit

执行效果图，默认为英文交互

cz-conventional-changelog

cz-conventional-changelog 是 Commitizen 的一个适配器（adapter），它专门为遵循 Conventional Commits 规范而设计。Conventional Commits 是一种社区广泛接受的提交消息格式规范，用于增强提交历史的可读性和自动化生成 CHANGELOG 文件。

配置

// package.json 
{ 
    "config": { 
        "config": {
            "commitizen": {
                "path": "./node_modules/cz-conventional-changelog",
                "disableScopeLowerCase": false,
                "disableSubjectLowerCase": false,
                "maxHeaderWidth": 100,
                "maxLineWidth": 100,
                "defaultType": "",
                "defaultScope": "",
                "defaultSubject": "",
                "defaultBody": "",
                "defaultIssues": "",
                "types": {
                    ...
                    "feat": {
                        "description": "A new feature",
                        "title": "Features"
                    },
                    ...
                }
            }
        }
    }
}

配置项

类型中英文提示示例

配置后的执行效果图

最佳实践

使用场景

• 代码提交

预期目标

• 提交时进行提交规范校验，校验信息包括：
  • 类型：必填、类型在预设的配置中
  • 描述：必填
• 提交时进行代码检测
  • 代码语法：检查语法是否正确，如果不正确抛出错误
  • 代码格式：自动格式化代码格式，使代码格式保持统一
• 通过辅助工具帮助开发同学规范提交信息
  • 配置 Commitizen

分析

如果要实现上述的预期目标，肯定是要在代码提交前执行。所以要用到Git Hooks中的钩子。pre-commit常用于运行代码风格检查、commit-msg常用于验证提交消息格式是否符合团队规范。

配置pre-commit脚本

// .husky > pre-commit

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

if [[ "$OS" == "Windows_NT" ]]; then
  npx.cmd lint-staged
else
  npx lint-staged
fi

// package.json
{
    "lint-staged": {
        "*.{js,jsx,vue,ts,tsx,html,vue,css,sass,less}": "eslint --fix"
    }
}

配置commit-msg脚本

// .husky > commit-msg

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

if [[ "$OS" == "Windows_NT" ]]; then
  npx.cmd --no-install commitlint -e $GIT_PARAMS
else
  npx --no-install commitlint -e $GIT_PARAMS
fi

脚本相关语法不再过多描述，主要是看if中执行的命令。

优势与不足

优势

• 使项目规范化，代码风格保持统一
• 易于后期的代码维护
• 减少新人加入项目后的代码上手难度

不足

在使用Commitizen辅助提交时，要使用命令行的方式，source tree 和 github desktop 的可视化工具就不太好用了。除此之外，source tree 和 github desktop校验失败时都会抛出错误，不使用Commitizen时，使用两者工具是没有问题的。

技术清单

原文链接：https://juejin.cn/post/7341320599737303081 作者：帅小伙子er