如何规范团队代码,小程序 ESLint+Prettier+lint-staged+commit message自动规范实践

502 阅读7分钟

如何规范团队代码,小程序 ESLint+Prettier+commit message+changelog+standard-version 自动规范实践

简介以及优势

ESLint

ESLint 中文官网

ESLint 是在 ECMAScript/JavaScript 代码中识别和报告模式匹配的工具,它的目标是保证代码的一致性和避免错误。 相较于 Prettier 更为自由,并且更为严苛,也可以发现 JS 当中的错误。

Prettier

Prettier 官网

Prettier 能够解析代码,使用你自己设定的规则来重新打印出格式规范的代码。正因为 Prettier Opinionated 的特性,所以我们不需要配置过多的规则,并且它能够支持更多编辑器的插件以及对于 html、css 等文件的格式化。

husky + lint-staged

husky Github 仓库

lint-staged Github 仓库

husky 让 Git 钩子变得容易,把 git 钩子的功能加到了 package 的 script 里面,使我们有能力直接调用其他命令而不用把钩子脚本写在项目的 .git/hook 里面, 方便团队间 git 钩子命令的共享.

lint-staged 检查所有被 git add 加入的文件,对这些文件执行你需要的命令。

由于每次在提交代码之前,对整个项目进行 eslint 处理耗时长且容易对老项目产生致命的 bug。为了解决这个问题,我们引入 husky + lint-staged 可以只对我们本次 commit 修改的代码进行 eslint 处理,让 linting 更有意义。这样,您可以确保没有错误进入存储库并强制执行代码样式。

commitizen

commitizen Github 仓库

Commitizen 是一个撰写合格 Commit message 的工具,当您使用 Commitizen 进行提交时,系统将提示您在提交时填写所有必填的提交字段。

commitlint

commitlint GitHub 仓库

commitlint 检查您的提交消息是否符合常规的提交格式。

conventional-changelog

conventional-changelog GitHub 仓库

如果你的所有 Commit 都符合 Angular 格式,那么发布新版本时, Change log 就可以用脚本自动生成。

生成的文档包括以下三个部分。

New features

Bug fixes

Breaking changes.

每个部分都会罗列相关的 commit ,并且有指向这些 commit 的链接。当然,生成的文档允许手动修改,所以发布前,你还可以添加其他内容。

standard-version

standard-version GitHub 仓库

利用 standard-version 进行版本控制,可以省去 git tag 手动打标签以及手动生成 changelog 的过程。

ESLint 引入

安装

NPM

npm install eslint --save-dev

配置使用规则

在 root 文件夹下创建文件 .eslintrc.js 和 .editorconfig

module.exports = {
  env: {
    browser: true,
    es2021: true,
    node: true,
  },
  extends: ["eslint:recommended"],
  parserOptions: {
    ecmaVersion: 12,
    sourceType: "module",
  },
  globals: {
    // 小程序的全局变量
    __DEV__: true,
    __WECHAT__: true,
    __ALIPAY__: true,
    __wxConfig: true,
    App: true,
    Page: true,
    Component: true,
    Behavior: true,
    wx: true,
    getApp: true,
    getCurrentPages: true,
  },
  rules: {
    // 这是我的配置,大家可以参考官方团队的配置
    "linebreak-style": ["error", "unix"], //换行样式
    quotes: ["error", "single", { avoidEscape: true }], //单引号
    semi: ["error", "always"], //分号
    "no-mixed-spaces-and-tabs": [2, false], //禁止混用tab和空格
    "object-curly-spacing": [0, "never"], //大括号内是否允许不必要的空格
    "no-multiple-empty-lines": [2, { max: 2 }], // 不允许多个空行
    "brace-style": [2, "1tbs", { allowSingleLine: true }], // if while function 后面的{必须与if在同一行,java风格。
    "no-redeclare": 2, //禁止重复声明变量
    "no-trailing-spaces": 1, //一行结束后面不要有空格
    "no-unused-vars": [2, { vars: "all", args: "none" }], //不能有声明后未被使用的变量或参数
    "default-case": 2, //switch语句最后必须有default
    "prefer-const": 2, //未被赋值的常量 使用const
    "template-curly-spacing": 1, //强制使用大括号内的间距 Bad: {people.name} 正确{ people.name }
    "array-bracket-spacing": [2, "never"], //是否允许非空数组里面有多余的空格 Bad:[ 'foo', 'bar' ] Good:['foo', 'bar'];
    "brace-style": [2, "1tbs", { allowSingleLine: true }], //大括号风格
    "key-spacing": [2, { beforeColon: false, afterColon: true }], //冒号前后的空格
  },
};

.editorconfig

root = true

[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

使用方法

终端中输入以下代码即可修复代码文件

// 全局安装eslint
eslint --fix index.js // fix后接文件名
// 没有全局安装eslint
npx eslint --fix index.js // fix后接文件名

在 package.json 中配置以下代码

"scripts": {
    "lint": "npx eslint --fix **/*.js",
  },

这样就可以在终端中输入以下代码就可以实现整个项目的 eslint 格式化

npm run lint

Prettier 引入

安装

NPM

npm install prettier --save-dev

配置使用规则

在 root 文件夹下创建文件 .prettierrc.js, 由于 prettier 是 Opinionated code formatter,所以配置项相对较少。

module.exports = {
  // 使用 4 个空格缩进
  tabWidth: 2,
  // 不使用缩进符,而使用空格
  useTabs: false,
  semi: true,
  singleQuote: true,
  overrides: [
    // 使用css/html的规则格式化wxss/wxml
    {
      files: "*.wxss",
      options: {
        parser: "css",
      },
    },
    {
      files: "*.wxml",
      options: {
        parser: "html",
      },
    },
  ],
};

使用方法

终端中输入以下代码即可修复代码文件

// 全局安装prettier
prettier --fix index.js // fix后接文件名
// 没有全局安装prettier
npx prettier --write index.js // fix后接文件名

在 package.json 中配置以下代码

"scripts": {
    "prettier": "npx prettier--write **/*.js",
  },

这样就可以在终端中输入以下代码就可以实现整个项目的 eslint 格式化

npm run prettier

ESLint 和 Prettier 结合使用

由于两者都会进行代码的格式化,我们并不希望代码的重复格式化以及发生不必要的冲突,所以我们要安装中间件来保证两者和谐运行

安装

npm install --save-dev eslint-config-prettier
npm install --save-dev eslint-plugin-prettier

配置使用方法

修改 .eslintrc.js 中的部分配置项

module.exports = {
  extends: ["eslint:recommended", "plugin:prettier/recommended"],
  plugins: ["prettier"],
};

husky + lint-staged 引入

安装

NPM

npm install husky --save-dev
npm install lint-staged --save-dev

配置使用规则

在 package.json 中配置

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "miniprogram/**/*.js": [
      "npx eslint --fix",
      "prettier --write",
      "git add"
    ]
  },
}

Commitizen

安装

npm install commitizen --save-dev
// 使用npx初始化常规更新日志适配器
npx commitizen init cz-conventional-changelog --save-dev --save-exact

配置使用规则

在 package.json 中配置

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

使用方法

在 git add 提交代码后,可以使用 npm run commit 或者 npx cz 来提示填写 commit 信息

git add .
npm run commit
// npx cz

踩坑

虽然 GitHub 仓库中提到 commitizen 可以结合 husky 使用,从而达到在 git commit 的钩子中执行 commitizen,但是至少 Windows 环境下使用这一方法会导致 commitizen 每次输入都会重复呈现提示信息,给人不友好的交互,因此并不建议在 Windows 环境下结合 husky 使用。

这个问题在其 GitHub 仓库的 issue 中有提及,不过暂时没有解决办法。issue 网址GitHub仓库用法说明

Commitlint

安装

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

配置使用规则

在 package.json 中配置

{
	"husky": {
    	"hooks": {
      		"pre-commit": "lint-staged", // 这个是之前配置的内容
      		"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    	}
  	},
}

新建 commitlint.config.js

module.exports = {
  extents: ["@commitlint/config-conventional"],
  rules: {
    "body-leading-blank": [1, "always"],
    "footer-leading-blank": [1, "always"],
    "header-max-length": [2, "always", 72],
    "scope-case": [2, "always", "lower-case"],
    "subject-case": [
      2,
      "never",
      ["sentence-case", "start-case", "pascal-case", "upper-case"],
    ],
    "subject-empty": [2, "never"],
    "subject-full-stop": [2, "never", "."],
    "type-case": [2, "always", "lower-case"],
    "type-empty": [2, "never"],
    "type-enum": [
      2,
      "always",
      [
        "build",
        "chore",
        "ci",
        "docs",
        "feat",
        "fix",
        "improvement",
        "perf",
        "refactor",
        "revert",
        "style",
        "test",
      ],
    ],
  },
};

使用方法

在你 git commit 提交代码的时候会自动检查你的 commit 信息是否符合规范

踩坑

虽然 GitHub 仓库中的初始步骤中使用的方法是借助以下代码生成 commitlint.config.js 文件,但是在 Windows 环境下生成的文件解码方式是 UTF-16,所以在自动运行时会报错。因此建议自己手动创建一个 commitlint.config.js,输入以上代码进行配置。

官网安装步骤

conventional-changelog

安装

 npm install --save-dev conventional-changelog-cli

配置使用规则

在 package.json 中配置

{
	"scripts": {
		"version": "npx conventional-changelog -p angular -i CHANGELOG.md -s"
	}
}

使用方法

npm run version
// 或者不进行配置,直接使用以下代码
npx conventional-changelog -p angular -i CHANGELOG.md -s
// 假如希望生成至今所有的改动
npx conventional-changelog -p angular -i CHANGELOG.md -s -r 0

standard-version

安装

npm install --save-dev standard-version

配置使用规则

在 package.json 中配置

{
  "scripts": {
    "release": "npx standard-version"
  }
}

使用方法

npm run release
## 或者不进行配置,直接使用以下代码
npx standard-version
## 使用以上两种方式,默认是生成下一个大版本,假如希望手动规定版本号
npm run release -- -r 1.1.0

Git 操作规范汇总

  1. 提交代码
git add .
npm run commit
git pull origin master
git push origin master
  1. 版本更新

提交所有上线前代码后

npm run release -- -r 1.0.0 ## 输入本次版本号
git push --follow-tags origin master