前端代码风格与提交规范_代码提交风格

一、代码规范概况

二、代码静态检查工具

ESLint js 代码规范

1. npm install eslint vue-eslint-parser --save-dev

2. npx eslint --init 生成 .eslintrc.cjs 文件

module.exports = {

  env: {

    browser: true,

    es2020: true

  },

  extends: [

    'eslint:recommended',

    'plugin:@typescript-eslint/recommended',

    'plugin:vue/vue3-recommended',

    'plugin:vue/vue3-essential',

    'prettier',

    'plugin:prettier/recommended'

  ],

  overrides: [

    {

      env: {

        node: true

      },

      files: ['.eslintrc.{js,cjs}'],

      parserOptions: {

        sourceType: 'script'

      }

    }

  ],

  parser: 'vue-eslint-parser',

  parserOptions: {

    parser: '@typescript-eslint/parser',

    ecmaVersion: 'latest',

    sourceType: 'module'

  },

  plugins: ['vue'],

  rules: {

    // eslint (http://eslint.cn/docs/rules)

    'no-var': 'error', // 要求使用 let 或 const 而不是 var

    'no-multiple-empty-lines': ['error', { max: 1 }], // 不允许多个空行

    'no-use-before-define': 'off', // 禁止在 函数/类/变量 定义之前使用它们

    'prefer-const': 'off', // 此规则旨在标记使用 let 关键字声明但在初始分配后从未重新分配的变量，要求使用 const

    'no-irregular-whitespace': 'off', // 禁止不规则的空白

    // typeScript (https://typescript-eslint.io/rules)

    '@typescript-eslint/no-unused-vars': 'off', // 禁止定义未使用的变量

    '@typescript-eslint/prefer-ts-expect-error': 'error', // 禁止使用 @ts-ignore

    '@typescript-eslint/no-inferrable-types': 'off', // 可以轻松推断的显式类型可能会增加不必要的冗长

    '@typescript-eslint/no-namespace': 'off', // 禁止使用自定义 TypeScript 模块和命名空间。

    '@typescript-eslint/no-explicit-any': 'off', // 禁止使用 any 类型

    '@typescript-eslint/ban-types': 'off', // 禁止使用特定类型

    '@typescript-eslint/explicit-function-return-type': 'off', // 不允许对初始化为数字、字符串或布尔值的变量或参数进行显式类型声明

    '@typescript-eslint/no-var-requires': 'off', // 不允许在 import 语句中使用 require 语句

    '@typescript-eslint/no-empty-function': 'off', // 禁止空函数

    '@typescript-eslint/no-use-before-define': 'off', // 禁止在变量定义之前使用它们

    '@typescript-eslint/ban-ts-comment': 'off', // 禁止 @ts-<directive> 使用注释或要求在指令后进行描述

    '@typescript-eslint/no-non-null-assertion': 'off', // 不允许使用后缀运算符的非空断言(!)

    '@typescript-eslint/explicit-module-boundary-types': 'off', // 要求导出函数和类的公共类方法的显式返回和参数类型

    // vue (https://eslint.vuejs.org/rules)

    'vue/no-v-html': 'off', // 禁止使用 v-html

    'vue/script-setup-uses-vars': 'error', // 防止<script setup>使用的变量<template>被标记为未使用，此规则仅在启用该no-unused-vars规则时有效。

    'vue/v-slot-style': 'error', // 强制执行 v-slot 指令样式

    'vue/no-mutating-props': 'off', // 不允许组件 prop的改变

    'vue/custom-event-name-casing': 'off', // 为自定义事件名称强制使用特定大小写

    'vue/attributes-order': 'off', // vue api使用顺序，强制执行属性顺序

    'vue/one-component-per-file': 'off', // 强制每个组件都应该在自己的文件中

    'vue/html-closing-bracket-newline': 'off', // 在标签的右括号之前要求或禁止换行

    'vue/max-attributes-per-line': 'off', // 强制每行的最大属性数

    'vue/multiline-html-element-content-newline': 'off', // 在多行元素的内容之前和之后需要换行符

    'vue/singleline-html-element-content-newline': 'off', // 在单行元素的内容之前和之后需要换行符

    'vue/attribute-hyphenation': 'off', // 对模板中的自定义组件强制执行属性命名样式

    'vue/require-default-prop': 'off', // 此规则要求为每个 prop 为必填时，必须提供默认值

    'vue/multi-word-component-names': 'off' // 要求组件名称始终为 “-” 链接的单词

  }

};

3. 创建 .eslintignore 文件

node_modules

dist

.husky

/public

Stylelint css 代码规范

1. npm install stylelint stylelint-config-standard postcss-html --save-dev

2. 创建 .stylelintrc.cjs 文件

// @see: https://stylelint.io

module.exports = {

  extends: "stylelint-config-standard",

  overrides: [

    // 扫描 .vue/html 文件中的<style>标签内的样式

    {

      files: ["**/*.{vue,html}"],

      customSyntax: "postcss-html"

    }

  ],

  /**

   * null  => 关闭该规则

   */

  rules: {

    "value-keyword-case": null, // 在 css 中使用 v-bind，不报错

    "no-descending-specificity": null, // 禁止在具有较高优先级的选择器后出现被其覆盖的较低优先级的选择器

    "function-url-quotes": "always", // 要求或禁止 URL 的引号 "always(必须加上引号)"|"never(没有引号)"

    "color-hex-length": "long", // 指定 16 进制颜色的简写或扩写 "short(16进制简写)"|"long(16进制扩写)"

    "rule-empty-line-before": "never", // 要求或禁止在规则之前的空行 "always(规则之前必须始终有一个空行)"|"never(规则前绝不能有空行)"|"always-multi-line(多行规则之前必须始终有一个空行)"|"never-multi-line(多行规则之前绝不能有空行。)"

    "font-family-no-missing-generic-family-keyword": null, // 禁止在字体族名称列表中缺少通用字体族关键字

    "property-no-unknown": null, // 禁止未知的属性(true 为不允许)

    "no-empty-source": null, // 禁止空源码

    "selector-class-pattern": null, // 强制选择器类名的格式

    "value-no-vendor-prefix": null, // 关闭 vendor-prefix(为了解决多行省略 -webkit-box)

    "selector-pseudo-class-no-unknown": [

      true,

      {

        ignorePseudoClasses: ["global", "v-deep", "deep"]

      }

    ]

  }

};

3. 创建 .stylelintignore 文件

三、代码格式化工具（Prettier）

1. 为什么使用 Prettier？ESLint 虽然是一个代码检测工具，可以检测代码质量问题并给出提示，但是提供的格式化功能有限，在代码风格上面做的不是很好，并且也只能格式化 JS，不支持 CSS, HTML 等语言。而在代码风格上面，Prettier 具有更加强大的功能，并且能够支持包括 JavaScript、TypeScript、CSS、Vue 等前端绝大部分的语言和文件格式。因此，我们一般把 Prettier 作为 ESLint 的插件使用，用 ESLint 进行代码校验，用 Prettier 统一代码风格。
2. npm install prettier eslint-config-prettier eslint-plugin-prettier --save-dev
3. 在 .eslintrc.cjs 文件里配置 extends: ["prettier", "plugin:prettier/recommended"]
4. 创建 .prettierrc.cjs 文件

   // @see: https://www.prettier.cn

   module.exports = {

     // 超过最大值换行

     printWidth: 130,

     // 缩进字节数

     tabWidth: 2,

     // 使用制表符而不是空格缩进行

     useTabs: true,

     // 结尾不用分号(true有，false没有)

     semi: true,

     // 使用单引号(true单双引号，false双引号)

     singleQuote: true,

     // 更改引用对象属性的时间 可选值"<as-needed|consistent|preserve>"

     quoteProps: 'as-needed',

     // 在对象，数组括号与文字之间加空格 "{ foo: bar }"

     bracketSpacing: true,

     // 多行时尽可能打印尾随逗号。（例如，单行数组永远不会出现逗号结尾。） 可选值"<none|es5|all>"，默认none

     trailingComma: 'none',

     // 在JSX中使用单引号而不是双引号

     jsxSingleQuote: false,

     //  (x) => {} 箭头函数参数只有一个时是否要有小括号。avoid：省略括号 ,always：不省略括号

     arrowParens: 'avoid',

     // 如果文件顶部已经有一个 doclock，这个选项将新建一行注释，并打上@format标记。

     insertPragma: false,

     // 指定要使用的解析器，不需要写文件开头的 @prettier

     requirePragma: false,

     // 默认值。因为使用了一些折行敏感型的渲染器（如GitHub comment）而按照markdown文本样式进行折行

     proseWrap: 'preserve',

     // 在html中空格是否是敏感的 "css" - 遵守CSS显示属性的默认值， "strict" - 空格被认为是敏感的 ，"ignore" - 空格被认为是不敏感的

     htmlWhitespaceSensitivity: 'css',

     // 换行符使用 lf 结尾是 可选值"<auto|lf|crlf|cr>"

     endOfLine: 'auto',

     // 这两个选项可用于格式化以给定字符偏移量（分别包括和不包括）开始和结束的代码

     rangeStart: 0,

     rangeEnd: Infinity,

     // Vue文件脚本和样式标签缩进

     vueIndentScriptAndStyle: false

   };

5. 创建 .prettierignore 文件

四、VSCode 插件

 安装插件

{
  "recommendations": [
    "vue.volar",
    "vue.vscode-typescript-vue-plugin",
    "editorconfig.editorconfig",
    "dbaeumer.vscode-eslint",
    "ms-vscode.vscode-typescript-next",
    "esbenp.prettier-vscode",
    "stylelint.vscode-stylelint"
  ]
} 

 配置插件的 settings.json 文件

{

  // #每次保存的时候自动格式化

  "editor.formatOnSave": true,

  "editor.codeActionsOnSave": {

    "source.fixAll.eslint": true,

    "source.fixAll.stylelint": true

  }

}

 配置 .editorconfig 文件

该文件是 EditorConfig for VS Code 插件的配置文件。这个文件里面定义的代码规范，会高于编译器默认的代码规范规则， 用于统一编辑器的规则。

五、git 提交规范 (Husky + Lint-staged + Commitlint)

 Husky

husky 是常见的 git hook 工具，使用 husky 可以挂载 Git 钩子，在我们进行 git commit 或 git push 等操作前，能够执行其它一些操作，比如进行 ESLint 检查，如果不通过，就不允许 commit 或 push。

npm install husky@8.0.2 --save-dev

npm set-script prepare "husky install"

npm run prepare

 Lint-staged

  Lint-staged 可以在 git staged 阶段的文件上执行 Linters，简单说就是可以指定只检查我们通过 git add 添加到暂存区的文件，可以避免我们每次检查都把整个项目的代码都检查一遍，从而提高效率。

  husky 的钩子只能执行一个指令，但是有时候我们希望能够在 git commit 之前执行多个指令，比如执行 ESLint、Stylelint 或 Commitlint 等操作。这时就需要 husky 结合 Lint-staged 一起使用。

npm install lint-staged@13.1.0 --save-dev

创建 lint-staged.config.cjs 文件

// eslint-disable-next-line no-undef

module.exports = {

  '*.{js,jsx,ts,tsx}': ['eslint --fix', 'prettier --write'],

  '{!(package)*.json,*.code-snippets,.!(browserslist)*rc}': ['prettier --write--parser json'],

  'package.json': ['prettier --write'],

  '*.vue': ['eslint --fix', 'prettier --write', 'stylelint --fix'],

  '*.{scss,less,css,html}': ['stylelint --fix', 'prettier --write'],

  '*.md': ['prettier --write']

};

Commitlint

Commitlint 可以对 Commit Message 进行检查。
npm install @commitlint/cli @commitlint/config-conventional --save-dev
创建 commitlint.config.cjs 文件进行配置

// eslint-disable-next-line no-undef

module.exports = {

  extends: ['@commitlint/config-conventional'],

  rules: {

    'type-enum': [

      2,

      'always',

      [

        'feat', // 新功能（feature）

        'fix', // 修补bug

        'bug', // 此项特别针对bug号，用于向测试反馈bug列表的bug修改情况

        'refactor', // 重构（即不是新增功能，也不是修改bug的代码变动）

        'style', // 样式（不影响代码运行的变动）

        'test', // 增加测试

        'chore', // 构建过程或辅助工具的变动

        'revert', // feat(pencil): add ‘graphiteWidth’ option (撤销之前的commit)

        'merge', // 合并分支， 例如： merge（前端页面）： feature-xxxx修改线程地址

        'docs', // 文档（documentation）

      ],

    ],

  },

};

 配置 Git 检查工作流

编辑 package.json 文件: { "scripts": { "lint-staged": "lint-staged" }, }

npx husky set .husky/pre-commit 'npm run lint-staged'

npx husky set .husky/commit-msg 'npx commitlint --edit $1'