规范

----现代软件架构的复杂性需要协同开发完成，如何高效地协同呢？无规矩不成方圆，无规范难以协同，比如，制订交通法规表面上是要限制行车权，实际上是保障公众的人身安全，试想如果没有限速，没有红绿灯，谁还敢上路行驶。对软件来说，适当的规范和标准绝不是消灭代码内容的创造性、优雅性，而是限制过度个性化，以一种普遍认可的统一方式一起做事，提升协作效率，降低沟通成本。代码的字里行间流淌的是软件系统的血液，质量的提升是尽可能少踩坑，杜绝踩重复的坑，切实提升系统稳定性，码出质量。

• 代码规范：阿里巴巴 Java 开发手册
• 注释规范：中文技术文档的写作规范
• Git Commit Message：conventional-changelog 标准

1.1 emoji 工具 git emoji

emoji	emoji 代码	commit 说明
✨	:sparkles:	feat ：新功能（feature）
🐛	:bug:	fix ：修补bug
📝	:memo:	docs ：文档（documentation）
💄	:lipstick:	style ： 格式（不影响代码运行的变动）
♻️	:recycle:	refactor ：重构（即不是新增功能，也不是修改bug的代码变动）
⚡️	:zap:	perf ：性能、体验优化
✅	:white_check_mark:	test ：增加、更新测试
👷	:construction_worker:	build ：构建过程或辅助工具的变动
⏪	:rewind:	revert ： 回滚某个提交
➖	:heavy_minus_sign:	降级依赖项
➕	:heavy_plus_sign:	升级依赖项
📦	:package:	添加或更新编译的文件或

Git 每次提交代码时，都要写 Commit message（提交说明），对于一个规范的 commit message 可以带给我们：

• 提供更多的历史信息，方便快速浏览；
• 可以过滤某些 commit（比如文档改动），便于快速查找信息；
• 可以直接根据 commit 生成 Change log 文件生成版本升级文档。

所以，规范 git commit 对于提高 git log 可读性、版本控制和 changelog 生成都有着重要的作用。

下面我们从 Commit message 格式、以及如何规范约束 commit 来学习使用。

Commit message 格式

Commit message 包括三个部分：Header，Body 和 Footer。结构如下：

<类型>([可选的作用域]): <描述> - header
// 空一格
[可选的正文] - body
// 空一格
[可选的脚注] - footer
​

其中，Header 是必需的，Body 和 Footer 可以省略。通常我们只需要编写 Header 即可。

Header 部分只有一行，包括三个字段：type（必需）、scope（可选）和 subject（必需）。

1、type：
type 用于说明 commit 的类别，一般允许使用下面7个标识。

• feat：新功能（feature）
• fix：修补bug
• perf: 优化性能
• docs：文档（documentation）
• style：格式（不影响代码运行的变动）
• refactor：重构（即不是新增功能，也不是修改bug的代码变动）
• test：增加测试
• chore：构建过程或辅助工具的变动

并且 type会被用于生成 changlog，如果 type为 feat和 fix，则该 commit 将肯定出现在 Change log 之中。

2、scope：
scope用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。

3、subject：
subject是 commit 目的的简短描述，不超过50个字符。

Commit 前的代码校验

在执行 git commit之前，需要进行代码规则检查能够确保进入 git 库的代码都是符合代码规则的。我们可以借助两个工具包来实现：lint-staged 和 husky。

• lint-staged：由于整个项目上运行 lint 速度会很慢，lint-staged 能够让 lint 只检测暂存区的文件；
• husky：可以让我们在项目中方便添加 git hooks。

1、安装：

npm install lint-staged husky@^4.3.8 -D

​

注意，上面我们指定了 husky 版本， 如果不指定版本号，将安装最新版本 husky（6.0.0以上），配置方式会有所不同，具体步骤可参考 文档配置。

2、在 package.json 中配置：

"scripts": {
  "lint": "eslint src --ext .js,.jsx,.ts,.tsx"
},
"husky": {
  "hooks": {
    "pre-commit": "lint-staged"
  }
},
"lint-staged": {
  "src/**/*.{js,json,css,scss,ts,tsx,md}": [
    "eslint"
  ]
},

​

3、使用：
首先确保项目内配置了 ESLint，参考配置 可以看这里。我们在 src/index.js 编写一个不规范的代码，执行：

git add .
git commit -m 'feat: 配置 commit lint code'

​

当变更文件内的代码校验不合格时，会中断提交。

规范 Commit message

Commitizen 是一个撰写合格 Commit message 的工具，提供了一组 Header.type 可选列表来规范 commit message。

1、安装：

npm install commitizen cz-conventional-changelog -D
​

2、在 package.json 内进行配置（使用业界 Angular 的 Commit message 格式）：

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

3、添加执行 commit 脚本：

"scripts": {
  "commit": "git-cz",
}

​

注意这里，凡是用到 git commit 命令，一律改为使用 git-cz。这时，就会出现选项，用来生成符合格式的 Commit message。

4、执行：

npm run commit
​

生成 CHANGELOG

当我们有了规范的 Commit message 后，就可以根据它们自动生成 CHANGELOG.md。

1、安装：

npm install conventional-changelog-cli -D
​

2、在 package.json 中配置执行脚本：

"scripts": {
  "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
}
​

• -p angular：指定风格，用来指定使用的 commit message 标准；
• -i CHANGELOG.md: 指定输出的文件名称；
• -s：指定读写同一文件；
• -r 0：指定增量更新，不会覆盖以前的更新日志。

默认 -i 会在工程根目录下生成 CHANGELOG.md 文件，如果想输出到指定目录下，比如在 docs 目录下生成，可以使用 -i ./docs/CHANGELOG.md。（前提需要确保目录存在）

注意：上面命令不会覆盖以前的 Change log，只会在 CHANGELOG.md 的头部加上自从上次发布以来的变动。

如果你想生成一个完整的 Change log 到 CHANGELOG.md 文件，需要运行下面的命令：

"scripts": {
  "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
}
​

3、执行：

npm run changelog
​