搭建Vue3组件库：第七章 规范化：Eslint + Prettier + Husky

为了项目能够长期健康的发展。代码的规范性建设非常重要。只有纪律严明的队伍才能不断打胜仗。

规范制定容易，执行的难度很大。

项目规范可以分为：

• 编码规范；
• 项目结构规范；
• 文件命名规范；
• git commit 版本规范；
• 工作流 workflow规范。

本节只考虑前四部分。

本章任务

• 编码与项目结构规范；
• Eslint 代码检查工具；
• Prettier 代码格式化工具；
• Git commit 提交检查脚本；
• Husky + git hook 提交前校验。

【task1】编码与项目结构规范

1、编码规范——js代码规范

• Airbnb JavaScript 风格指南
• JavaScript Standard Style
• 百度前端规范 4.5K star

2、编码规范——css代码规范

• styleguide
• spec

对于编码规范，通常会依赖 eslint 这种代码检查工具。 eslint 提供了 airbnb 、google、eslint默认三种编码规范。其实无论选择哪一种规则都可以很好地保证代码的可读性。所以大家使用 eslint 默认规则就好。

3、目录文件规范

.
├── config               # 配置文件
├── coverage            # 覆盖率报告
├── demo                # 代码范例
├── docs                # 文档
├── node_modules  
├── scripts              # 脚本 发布、提交信息检查
├── src                  # 组件代码
└── types                # TS类型定义

4、文件命名规范

├── src                 # 组件代码
    └── button       # 组件包名
         ├── index.ts   # 组件入口
         ├── Button.tsx  # 组件代码  
         └── __tests__   # 测试用例
                  └── Button.test.ts   

• 包名：小写 + 中划线；
• 统一入口文件： index.ts；
• 组件代码： 大驼峰；
• 测试用例代码 ： 测试对象名+ .test.ts。

【task2】Eslint + Prettier代码检查工具

通常代码的检查工作交给 eslint 和 prettier 共同完成。其中 eslint 主要是完成对于代码语法的检查工作，比如：是否有声明但是没有使用的变量。而 prettier 主要专注于代码格式的调整功能。prettier 通常会以eslint 插件的形式使用，一般无需直接运行。

另外 eslint 在环境下还需要配置专门针对 Vue 框架的 eslint-plugin-vue 插件。

• 安装依赖

pnpm i eslint -D
# ESLint 专门解析 TypeScript 的解析器
pnpm i @typescript-eslint/parser -D
# 内置各种解析 TypeScript rules 插件
pnpm i @typescript-eslint/eslint-plugin -D

pnpm i eslint-formatter-pretty -D
pnpm i eslint-plugin-json -D
pnpm i eslint-plugin-prettier -D
pnpm i eslint-plugin-vue -D
pnpm i @vue/eslint-config-prettier -D
pnpm i babel-eslint -D
pnpm i prettier -D

• 配置Eslint

文件名（根目录）：.eslintrc.cjs

module.exports = {
  root: true,
  env: {
    browser: true,
    es2020: true,
    node: true,
    jest: true,
  },
  globals: {
    ga: true,
    chrome: true,
    __DEV__: true,
  },
  // 解析 .vue 文件
  parser: 'vue-eslint-parser',
  extends: [
    'plugin:json/recommended',
    'plugin:vue/vue3-essential',
    'eslint:recommended',
    '@vue/prettier',
  ],
  plugins: ['@typescript-eslint'],
  parserOptions: {
    parser: '@typescript-eslint/parser', // 解析 .ts 文件
  },
  rules: {
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'prettier/prettier': 'off',
  },
}

• 配置ES忽略文件

文件名（根目录）：.eslintignore

*.sh
node_modules
lib
coverage
*.md
*.scss
*.woff
*.ttf
src/index.ts
dist

• 配置启动命令

文件名：package.json

{
  "scripts": {
    "lint": "eslint --fix --ext .ts,.vue src",
    "format": "prettier --write \"src/**/*.ts\" \"src/**/*.vue\"",
  },
}

• 启动命令

pnpm lint

控制台

WARNING: You are currently running a version of TypeScript which is not officially supported by @typescript-eslint/typescript-estree.

You may find that it works just fine, or you may not.

SUPPORTED TYPESCRIPT VERSIONS: >=3.3.1 <4.9.0

YOUR TYPESCRIPT VERSION: 4.9.3

Please only submit bug reports when using the officially supported version.

这里提示我们ts的版本太高。

npm view typescript version

使用以上命令查看你的ts版本

【task3】Husky + git hooks 自动化提交验证

为了确保只有合格的代码才能够提交到仓库。 需要配置自动化脚本，确保代码在提交前通过了代码验证工具的检验。

实际上 git 本身就设计了生命周期钩子来完成这个任务。但是设置过程比较复杂。所以通常情况下会使用 husky 来简化配置。

• 安装依赖

pnpm i husky -D

• 添加husky脚本

npm set-script prepare "husky install"

• 运行husky脚本

pnpm prepare

此时会生成.husky目录

注意：在执行此操作之前需配置好git关联仓库

• 添加生命周期钩子

首先配置一个钩子，在 commit 提交前，必须执行 lint 代码校验。

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

• 修改 hooks 程序

文件名：.husky/pre-commit

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

pnpm run lint

配置完成后，commit 一次代码测试一下是否有效。

接着还需要配置在 push 之前通过单元测试的钩子。方法类似。

• 添加push生命周期钩子

npx husky add .husky/pre-push "pnpm test:run"

由于 vitest 默认是以伺服模式运行，所以需要写一个专门的脚本让测试运行在伺服模式下 packages.json

文件名：package.json

"scripts": {
    "test:run": "vitest run",
  },

• 修改hooks程序。

文件名：.husky/pre-push

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

pnpm test:run

Git commit 提交规范

提交规范主要是为了让开发者提交完整的更新信息。方便查阅。大家可以围观一下 Vue 的 Github。拥有清晰 commit 信息非常有助于查阅代码。

目前最为流行的提交信息规范来自于 Angular 团队。

规范中，主要就是要求提交内容要进行分类并填写内容，更为严格的规定是要求标注开发模块。

• type：commit 的类型；
• feat：新功能、新特性；
• fix: 修改 bug；
• perf：更改代码，以提高性能；
• refactor：代码重构（重构，在不影响代码内部行为、功能下的代码修改）；
• docs：文档修改；
• style：代码格式修改, 注意不是 css 修改（例如分号修改）；
• test：测试用例新增、修改；
• build：影响项目构建或依赖项修改；
• revert：恢复上一次提交；
• ci：持续集成相关文件修改；
• chore：其他修改（不在上述类型中的修改）；
• release：发布新版本；
• workflow：工作流相关文件修改。

示例：

# 示例1
fix(global):修复checkbox不能复选的问题
# 示例2 下面圆括号里的 common 为通用管理的名称
fix(common): 修复字体过小的BUG，将通用管理下所有页面的默认字体大小修改为 14px
# 示例3
fix: value.length -> values.length

下面配置一个工具用于在提交时自动检查 commit 信息是否符合要求。

安装工具验证脚本 commitlint，并且配置一个 commitlint 内容插件来确定一种 msg 风格。

• 安装commitlint

pnpm i -D @commitlint/config-conventional@"17.0.2" @commitlint/cli@"17.0.2"

• 添加配置文件

文件名：commitlint.config.js

module.exports = {extends: ['@commitlint/config-conventional']}

• 添加钩子

将 commitlint 脚本添加到 githooks 中， 让每次提交前都验证信息是否正常

npx husky add .husky/commit-msg ""

• 修改钩子内容

文件名：.husky/commit-msg

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

npx --no -- commitlint --edit "$1"

配置完成后，你可以测试一下。

当你提交代码没有按照规范填写 commit message 时，就会出现报错并且阻止你提交代码。