1. 代码格式化

1.1 工具介绍

Untitled 1.png

ESLint 是一款用于查找并报告代码中问题的工具
Stylelint 是一个强大的现代 CSS 检测器
Prettier 是一款强大的代码格式化工具，支持多种语言
lint-staged 是一个在 git 暂存文件上运行 linters 的工具
husky 是 Git Hook 工具，可以设置在 git 各个阶段触发设定的命令

1.2 配置说明

1.2.1 ESLint 配置

在项目根目录下增加 .eslintrc.js 文件进行配置，配置项详见官方文档，以下为参考配置：

npm i -D eslint eslint-plugin-vue eslint-plugin-import eslint-import-resolver-typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin prettier eslint-plugin-prettier eslint-config-prettier

module.exports = {
  // 此项是用来告诉 eslint 找当前配置文件不能往父级查找
  root: true,
  // 全局环境
  env: {
    browser: true,
    node: true,
  },
  // 指定如何解析语法，eslint-plugin-vue 插件依赖vue-eslint-parser解析器
  parser: "vue-eslint-parser",
  // 优先级低于parse的语法解析配置
  parserOptions: {
    // 指定ESlint的解析器
    parser: "@typescript-eslint/parser",
    // 允许使用ES语法
    ecmaVersion: 2020,
    // 允许使用import
    sourceType: "module",
    // 允许解析JSX
    ecmaFeatures: {
      jsx: true,
    },
  },
  extends: [
    "eslint:recommended", // 引入 ESLint的核心功能并且报告一些常见的共同错误
    "plugin:import/recommended", // import/export语法的校验
    "plugin:import/typescript", // import/export 语法的校验（支持 TS）
    // 'plugin:vue/essential' // vue2 版本使用
    // 'plugin:vue/recommended', // vue2 版本使用
    "plugin:vue/vue3-essential", // vue3 版本使用
    "plugin:vue/vue3-recommended", // vue3 版本使用
    "plugin:@typescript-eslint/recommended",
    "prettier", // prettier 要放在最后！
  ],
  plugins: ["prettier"],
  rules: {
    "prettier/prettier": "error",
    "@typescript-eslint/explicit-module-boundary-types": "off",
    "no-undef": "off",
    // 更多规则详见：http://eslint.cn/docs/rules/
  },
  settings: {
    "import/parsers": {
      "@typescript-eslint/parser": [".ts", ".tsx"],
    },
    "import/resolver": {
      typescript: {
        alwaysTryTypes: true,
      },
    },
  },
};

💡当 ESLint 同时使用 prettier 的时候，prettier 和 ESLint 可能存在一些规则冲突，我们需要借助 eslint-plugin-prettier 和 eslint-config-prettier 进行解决，在安装完依赖包后在 .eslintrc.js 配置文件中进行添加如下内容：

module.exports = {
	"extends": [
    // 其他扩展内容...
    "prettier" // prettier 要放在最后！
  ],
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error"
  },
}

1.2.2 StyleLint 配置

在项目根目录下增加 .stylelintrc.js 文件进行配置，配置项详见官方文档，以下为参考配置：

npm i -D stylelint stylelint-config-standard stylelint-order stylelint-config-rational-order prettier stylelint-prettier stylelint-config-prettier postcss-html postcss-less stylelint-config-recommended-vue

module.exports = {
  extends: [
    'stylelint-config-standard', // 官方 stylelint 规则
    'stylelint-config-rational-order', // 属性排列顺序规则
    /*
     * 通过安装 stylelint-prettier，设置 'stylelint-prettier/recommended'，其包含了三个操作
       plugins: ['.'],
       extends: ['stylelint-config-prettier'], // 需要安装 stylelint-config-prettier
       rules: {'prettier/prettier': true},
     */
    'stylelint-prettier/recommended',
  ],
  plugins: [
    'stylelint-order', // CSS 属性排序
  ],
  rules: {
    // 更多规则详见：https://stylelint.io/user-guide/rules/list
  },
};

💡当 StyleLint 同时使用 prettier 的时候，prettier 和 StyleLint 可能存在一些规则冲突，我们需要借助 stylelint-prettier 和 stylelint-config-prettier 进行解决，在安装完依赖包后在 .stylelintrc.js 配置文件中进行添加如下内容：

module.exports = {
  extends: [
    /*
     * 通过安装 stylelint-prettier，设置 'stylelint-prettier/recommended'，其包含了三个操作
       plugins: ['.'],
       extends: ['stylelint-config-prettier'], // 需要安装 stylelint-config-prettier
       rules: {'prettier/prettier': true},
     */
    'stylelint-prettier/recommended',
  ],
};

1.2.3 Prettier 配置

在项目根目录下增加 .prettierrc.js 文件进行配置，配置项详见官方文档，以下为参考配置：

npm i -D prettier

module.exports = {
  // 更多规则详见：https://prettier.io/docs/en/options.html
  printWidth: 120, // 单行长度
  tabWidth: 2, // 缩进长度
  useTabs: false, // 使用空格代替tab缩进
  semi: true, // 句末使用分号
  singleQuote: true, // 使用单引号
  bracketSpacing: true, // 在对象前后添加空格-eg: { foo: bar }
  quoteProps: 'consistent', // 对象的key添加引号方式
  trailingComma: 'all', // 多行时尽可能打印尾随逗号
  jsxBracketSameLine: true, // 多属性html标签的‘>’折行放置
  arrowParens: 'always', // 单参数箭头函数参数周围使用圆括号-eg: (x) => x
  jsxSingleQuote: true, // jsx中使用单引号
  proseWrap: 'preserve',
  htmlWhitespaceSensitivity: 'ignore', // 对HTML全局空白不敏感
};

1.2.4 husky 和 lint-staged 配置

step1. 初始化 husky

npx husky-init && npm install

step2. 在 .husky/pre-commit 文件中进行修改（注意区别 husky@7 与 husky@4 的设置方式）

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

npx lint-staged

step3. 安装 lint-statged 并在 package.json 中进行设置

npm i -D lint-staged

{
  "lint-staged": {
    "*.{js,ts,vue}": [
      "eslint --fix",
      "prettier --write",
      "git add"
    ],
    "*.{css,less,vue}": [
      "stylelint --fix",
      "prettier --write",
      "git add"
    ]
  }
}

1.3 使用参考

代码提交：根据上述工具配置，代码在提交仓库时进行检查和格式化，实现代码风格统一；
本地保存：在 VSCode 中进行配置，使得代码在保存的时候即按照相应的规则进行格式化；

如何在 VSCode 中进行配置使得能够自动按照相应的规则进行格式化呢？接下来进入第二章《编辑器配置》。

2. 编辑器配置

2.1 VSCode 配置

2.1.1 配置内容

所有 VSCode 配置自定义的内容（包括插件部分）都在 setting.json 文件中，以下为参考配置：

{
  "editor.tabSize": 2,
  "window.zoomLevel": 0,
  "editor.fontSize": 14,
  "editor.formatOnPaste": true,
  "editor.formatOnSave": true,
  "editor.multiCursorModifier": "ctrlCmd",
  "editor.snippetSuggestions": "top",
  "eslint.codeAction.showDocumentation": {
    "enable": true
  },
  "eslint.run": "onSave",
  "eslint.format.enable": true,
  "eslint.options": {
    "extensions": [
      ".js",
      ".vue",
      ".ts",
      ".tsx"
    ]
  },
  "eslint.validate": [
    "javascript",
    "typescript",
    "vue"
  ],
  "stylelint.validate": [
    "css",
    "less",
    "postcss",
    "scss",
    "sass",
    "vue",
  ],
  // 保存时按照哪个规则进行格式化
  "editor.codeActionsOnSave": {
    "source.fixAll": true,
    "source.fixAll.eslint": true
  },
  "files.autoSave": "afterDelay", // 文件自动保存
  "files.autoSaveDelay": 2000, // 2s 后文件自动保存
}

参考资料： VS Code 使用指南、 VS Code 中 Vetur 与 prettier、ESLint 联合使用

2.1.1 插件推荐

Eslint: Integrates ESLint JavaScript into VS Code
stylelint: Official Stylelint extension for Visual Studio Code
Prettier: Code formatter using prettier
EditorConfig: EditorConfig Support for Visual Studio Code
Npm Intellisense: VS Code plugin that autocompletes npm modules in import statements
Path Intellisense: VS Code plugin that autocompletes filenames
Auto Rename Tag: Auto rename paired HTML/XML tag
Auto Close Tag: Automatically add HTML/XML close tag
Code Spelling Checker: Spelling checker for source code
Volar / Vetur: Language support for Vue 3 / Vue tooling for VS Code

2.2 EditorConfig 配置

EditorConfig 的优先级高于编辑器自身的配置，因此可用于维护不同开发人员、不同编辑器的编码风格。在项目根目录下增加 .editorconfig 文件进行配置即可，以下为参考配置：

# Editor configuration, see http://editorconfig.org

# 表示是最顶层的 EditorConfig 配置文件
root = true

[*] # 表示所有文件适用
charset = utf-8 # 设置文件字符集为 utf-8
indent_style = space # 缩进风格（tab | space）
indent_size = 2 # 缩进大小
end_of_line = lf # 控制换行类型(lf | cr | crlf)
insert_final_newline = true # 始终在文件末尾插入一个新行
trim_trailing_whitespace = true # 去除行尾的任意空白字符

3. Commit Message 格式化

3.1 工具介绍

Conventional Commits 约定式提交规范是一种用于给提交信息增加人机可读含义的规范，可以通过以下工具来进行检查、统一和格式化：

commitlint：检查您的提交消息是否符合 conventional commit format
commitizen：帮助撰写规范 commit message 的工具
cz-customizable：自定义配置 commitizen 工具的终端操作
commitlint-config-cz：合并 cz-customizable 的配置和 commitlint 的配置

3.2 配置说明

3.2.1 格式化配置

step1. 安装 commitizen 和 cz-customizable

npm install -D commitizen cz-customizable

step2. 在 package.json 添加以下内容：

{
  "config": {
    "commitizen": {
      "path": "node_modules/cz-customizable"
    }
  }
}

step3. 在项目根目录下增加 .cz-config.js 文件进行配置即可，以下为参考配置：

module.exports = {
  // type 类型
  types: [
    { value: 'feat', name: 'feat: 新增功能' },
    { value: 'fix', name: 'fix: 修复 bug' },
    { value: 'docs', name: 'docs: 文档变更' },
    { value: 'style', name: 'style: 代码格式改变（不影响功能）' },
    { value: 'refactor', name: 'refactor: 代码重构（不包括 bug 修复、功能新增）' },
    { value: 'perf', name: 'perf: 性能优化' },
    { value: 'test', name: 'test: 添加或修改测试用例' },
    { value: 'build', name: 'build: 构建流程或外部依赖变更' },
    { value: 'ci', name: 'ci: 修改 CI 配置或脚本' },
    { value: 'chore', name: 'chore: 对构建过程或辅助工具和库的更改（不影响源文件、测试用例）' },
    { value: 'revert', name: 'revert: 回滚 commit' },
  ],
  // scope 类型
  scopes: [
    ['components', '组件相关'],
    ['hooks', 'hook 相关'],
    ['utils', 'utils 相关'],
    ['styles', '样式相关'],
    ['deps', '项目依赖'],
    // 如果选择 custom，后面会让你再输入一个自定义的 scope。也可以不设置此项，把后面的 allowCustomScopes 设置为 true
    ['custom', '以上都不是，我要自定义'],
  ].map(([value, description]) => {
    return {
      value,
      name: `${value.padEnd(30)} (${description})`,
    };
  }),
  // 交互提示信息
  messages: {
    type: '确保本次提交遵循 Angular 规范！\n选择你要提交的类型：',
    scope: '选择一个 scope（可选）：\n',
    customScope: '请输入自定义的 scope：\n', // 选择 scope: custom 时会出现的提示
    subject: '填写简短精炼的变更描述：\n',
    body: '填写更加详细的变更描述（可选）。使用 "|" 换行：\n',
    breaking: '列举非兼容性重大的变更（可选）：\n',
    footer: '列举出所有变更的 ISSUES CLOSED（可选）：\n',
    confirmCommit: '是否确认提交？',
  },
  // 设置只有 type 选择了 feat 或 fix，才询问 breaking message
  allowBreakingChanges: ['feat', 'fix'],
  // subject 限制长度
  subjectLimit: 100,
};

step4. 新增 husky 配置，使得提交 commit message 时触发 commitizen，快捷命令如下：

npx husky add .husky/prepare-commit-msg "exec < /dev/tty && node_modules/.bin/cz --hook || true"

注意，commitizen 如果是全局安装，则使用下面的快捷命令：

npx husky add .husky/prepare-commit-msg "exec < /dev/tty && git cz --hook || true"

3.2.2 格式检查配置

step1. 安装 commitlint 和 commitlint-config-cz ****依赖：

npm install --save-dev @commitlint/{config-conventional,cli} commitlint-config-cz

step2. 在项目根目录下增加 commitlint.config.js 文件进行配置即可，以下为配置内容：

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

step3. 新增 husky 配置，使得提交 commit message 时触发 commitlint 检验，配置内容如下：

npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

3.3 使用参考

在命令行输入 git commit，然后根据命令行提示输入相应的内容，完成之后则会自动生成符合规范的 commit message，从而实现提交信息的统一。

4. 代码规范参考

4.1 JS/TS 规范

社区类代码风格：

Airbnb JavaScript Style Guide：github.com/airbnb/java…
Clean Code Javascript：github.com/ryanmcdermo…
Code Guide by @AlloyTeam：alloyteam.github.io/CodeGuide/
JavaScript Standard Style：github.com/standard/st…

工具类代码风格：

ESLint 规则：eslint.cn/docs/rules/
ESLint 扩展：
- eslint-plugin-vue 针对 Vue2/3 规则
- eslint-config-standard 对应 JavaScript Standard Style 社区规则
- eslint-config-airbnb 对应 Airbnb JavaScript Style Guide 社区规则

4.2 CSS 规范