🚦如何搭建团队自定义代码规范！

CRAB
3,127 阅读6分钟

来自处女座的强迫症😭
搬砖体验🛵🛵🛵大大提升
开发效率🚀🚀🚀也大大提高

🌚🌚对于存量代码，也能渐进式📈规范

🚧 eslint～代码质量

eslint 主要用来检查代码的开发质量，例如是否出现变量定义后未使用/使用时未定义/debugger语句等。除此之外，eslint还可以集中对 js、ts、vue 等部分文件类型做代码风格检查。这些可以通过配置进行检测。

🚩 安装使用

  1. 安装 Eslint 编辑器插件
  2. 安装 npm 包
    npm i eslint -D

    插件和 npm 包的区别，实际是 eslint 的 npm 包进行代码检查，安装插件方便在 VSCode 开发时提示代码问题及使用格式化功能。

  3. 新增配置
    在项目根目录下创建 .eslintrc.js 文件，并配置好规则。
  4. 新增忽略配置
    在项目的根目录下创建 .eslintignore 文件，并配置好忽略校验的文件。
    Eslint是默认忽略/node_modules/的文件的，这个目录不需要配置。
  5. 测试 eslint 是否生效
    • 校验某个文件
      npx eslint XXX.js
    • --ext 可以指定校验的文件类型
      npx eslint --ext .js,.jsx,.vue src
    • --fix 可以修复 elint 部分规则
      npx eslint --fix --ext .js

Rules Reference - ESLint - Pluggable JavaScript Linter

⛺️ prettier～代码风格

prettier 的作用是对代码进行风格检查，针对的文件类型更加全面，例如js、ts、css、html、json、md等。这些可以通过配置进行检测。

🚩 安装使用

  1. 安装 prettier 编辑器插件
  2. 安装 npm 包
    npm i prettier -D

    插件和 npm 包的区别，插件是给VSCode编辑器本地提示以及格式化代码，prettier包是用于命令行方式进行风格检查。

  3. 新增配置
    在项目根目录下创建 .prettierrc 文件，并配置好规则。
  4. 新增忽略配置
    在项目的根目录下创建 .eslintignore 文件，并配置好忽略校验的文件。
  5. 测试 prettier 是否生效
    • 格式化某个文件
      npx prettier --write XX.js
    • 格式化全部文件
      npx prettier --write .
    • 检查文件是否已格式化
      npx prettier --check .

👹 eslint prettier冲突解决

因为eslint中继承了 eslint-config-standard，当 eslint 有些风格检查配置与 prettier 配置相互冲突时，编辑器设置了保存时自动格式化并修复时，启用了eslint --fix修复时，问题虽然修复了，但因为又运行了 prettier 格式化，所以会被 prettier 恢复。

🚩 解决方案

  • 用 eslint-config-prettier 关闭 eslint 中与 prettier 相互冲突的规则
  • 用 eslint-plugin-prettier 使 eslint 风格检查时使用 prettier 的配置，各司其职
  1. 安装依赖
    npm i eslint-config-prettier eslint-plugin-prettier -D
  2. 修改 eslint 配置
    ✅ 这样再保存，自动格式化和修复也能正常工作了。

🚨 husky～git hooks钩子

git 执行特定事件（如 commit、push、receive 等）时，触发运行的脚本就是 githooks，类似于框架的生命周期。githooks 保存在 .git 文件夹中，如果没有该文件，需要执行git init初始化下。
husky是一个让我们使用git hook更加方便的工具。下面会用到 pre-commit 和 commit-msg 两个钩子，都会在 git commit 执行前执行，可以使用 git commit --no verify 命令绕过该钩子

🚩 安装使用

  1. 安装依赖
    npm i husky -D

  2. 启用 husky
    npx husky install

  3. 创建 pre-commit 钩子和 commit-msg 钩子
    npx husky add .husky/pre-commit \"npx --no-install lint-staged\"
    npx husky add .husky/commit-msg \"npx --no-install commitlint -e $1\"
    git add .husky

    这里用到了 lint-staged 和 commitlint 工具对代码和提交信息进行校验，后续安装后就可以实现 git commit 前拦截进行代码检查。

🎢 lint-staged～过滤stage暂存区文件

lint-staged 是一个在 git 暂存文件上运行 lint 的工具。如果在整个项目上运行lint，一方面速度会很慢，另一方面对于旧项目会有一堆不符合规范，但不影响功能的存量代码。lint-staged能够让lint只检测暂存区的文件，这样速度很快，也能实现渐进性对项目进行规范。

🚩 安装使用

  1. 安装（ node 版本 ^14.13.1 || >=16.0.0）
    npm install -D lint-staged
  2. 配置 lint-staged
    在 package.json 新增 lint-staged 字段配置对不同文件执行检查并修复。
    另外，在 pre-commit 钩子上面已经配置好执行 lint-staged 了。
  3. 测试
    ✅git add提交修改文件之后，运行 npx lint-staged 就会对文件进行 lint 校验

📝 cz～自定义commit msg规范

commitizen 是一个能够快速地帮助完成提交信息补充的工具。cz-customizable 是一个可以自定义提交说明的规范适配器，默认会去读取项目中.cz-config.js配置。

🚩 安装使用

  1. 安装
    npm install -D commitizen cz-customizable
  2. 添加适配器
    在 package.json 新增 config
  3. 配置规范
    在项目根目录下新建 .cz-config.js
  4. 测试
    npx git cz
    image.png ✅ 此时就可以根据提交说明的提示输入。

除了使用 cz-customizable，也可以用 commitlint prompt 字段使用 prompt 提词器，需要安装 @commitlint/cz-commitlint 和 @commitlint/prompt-cli 依赖（ commitlint - Lint commit messages）

另外，commitizen 实际上只起提示作用，对规范做不到强制要求。所以仍需要配合 commitlint 和 husky 来使用。根据实际情况选择使用 git commit 或 git cz 。

🔻 注意：如果使用git cz，请先执行 npx lint-staged 以免代码检查不通过，commit 说明jiu白写了。

📽 commitlint～commit msg格式校验工具

目前认同范围最广的基础规范是约定式提交 (conventionalcommits)。它提供了一组用于创建清晰的提交历史的简单规则。即：
commitlint 也是依赖 husky，目的是在提交前对 commit 提交的说明文字进行校验。上面使用了 cz 自定义提交规范，所以需要使用 commitlint-config-cz 对定制化提交说明进行校验。

commitlint 作用于 commit-msg 阶段，commitizen作用于 pre-commit。

🚩 安装使用

  1. 安装
    npm install -D commitlint-config-cz @commitlint/cli

  2. 配置 commitlint.config.js
    配置声明继承 cz 校验适配器，并配置校验规则

  3. 配置 commit-msg 钩子
    上面 husky 已经配置过了
    Husky - Git hooks

  4. 测试
    ✅ 如果提交的 subject 说明为空时，无法提交成功。
    image.png

📋 standard-version～版本管理（生成commit日志）

standard-version 是一款遵循语义化版本（semver）和 commit message 标准规范的版本自动化工。它能自动升级版本、打 tag 和生成 changelog。

🚩 安装使用

  1. 安装
    npm install -D standard-version

  2. 配置.versionrc.js
    hidden 可以将该 type 的提交记录写入changlog，默认false

  3. 配置package发布命令

    {
    "scripts": {
        "release": "standard-version",
        "release:first": "standard-version --first-release "
    }
}

  4. 测试
    首次发布执行npm run release:first，会在根目录生成日志changelog，之后发布版本只需执行npm run release。

🚩 版本更新规则

版本号 1.0.0（major.minor.patch）

  • feat 会更新 minor

  • fix 会更新 patch

  • BREAKING CHANGES 会更新 major
    假设您的代码的最后一个版本是1.0.0，也可以通过命令发布为指定1.1.0版本

    • npm run release -- --release-as 1.1.0
    • 或者npm run release -- --release-as minor

    image.png

📍 总结

至此，整个过程从

  • git add 修改文件后
  • eslint、prettier 代码检查
  • husky git 钩子启动
  • lint-staged 在 pre-commit 仅对暂存区进行代码格式化与修复
  • cz 在 pre-commit 阶段对提交说明进行提示
  • commitlint 在 commit-msg 阶段对提交说明是否规范进行校验，最终完成 commit 操作
  • 版本发布时，使用 standard-version 自动更新版本、打 tag 并输出清晰直观的 changelog

就完成了，实现了🥊 整个团队如何从0到1搭建自定义规范。

avatar
文章
阅读
粉丝