前端开发提交规范

发表于 更新于 分类于

格式化规范

背景

在一个多人协作的项目中，不同的开发人员写的代码的风格不太一样，比如是否需要在行末加分号，换行、空格、缩进、项目中散落的 console 处理方法、单行代码最大长度等等，如果项目中没有统一的规范就会导致代码风格的五花八门，不利于代码的阅读和维护。

目标

为了项目中有统一的编码规范，我们使用 eslint + prettier 来进行约束。

  1. 使用 eslint + prettier 添加统一代码规范
  2. 格式化现有项目下的不符合规范的文件
  3. 配置编辑器，自动检测新增或修改的代码的规范合法性

配置

安装 eslint

1
npm i -D @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint eslint-config-prettier eslint-config-standard eslint-define-config eslint-plugin-import eslint-plugin-node eslint-plugin-prettier eslint-plugin-promise eslint-plugin-vue

添加 .eslintrc.js 配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
const { defineConfig } = require("eslint-define-config");
module.exports = defineConfig({
  root: true,
  env: {
    browser: true,
    node: true,
    es6: true
  },
  parser: "vue-eslint-parser",
  parserOptions: {
    parser: "@typescript-eslint/parser",
    ecmaVersion: 2020,
    sourceType: "module",
    jsxPragma: "React",
    ecmaFeatures: {
      jsx: true
    }
  },
  extends: ["plugin:vue/recommended", "plugin:@typescript-eslint/recommended"],
  rules: {
    "no-unused-vars": "off",
    "vue/multi-word-component-names": "off",
    "vue/script-setup-uses-vars": "error",
    "@typescript-eslint/no-unused-vars": "off",
    "@typescript-eslint/ban-ts-ignore": "off",
    "@typescript-eslint/explicit-function-return-type": "off",
    "@typescript-eslint/no-explicit-any": "off",
    "@typescript-eslint/no-var-requires": "off",
    "@typescript-eslint/no-empty-function": "off",
    "vue/custom-event-name-casing": "off",
    "no-use-before-define": "off",
    "@typescript-eslint/no-use-before-define": "off",
    "@typescript-eslint/ban-ts-comment": "off",
    "@typescript-eslint/ban-types": "off",
    "@typescript-eslint/no-non-null-assertion": "off",
    "@typescript-eslint/explicit-module-boundary-types": "off",
    "@typescript-eslint/no-unused-vars": [
      "error",
      {
        argsIgnorePattern: "^_",
        varsIgnorePattern: "^_"
      }
    ],
    "no-unused-vars": [
      "error",
      {
        argsIgnorePattern: "^_",
        varsIgnorePattern: "^_"
      }
    ],
    "space-before-function-paren": "off",
    "vue/attributes-order": "off",
    "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",
    "vue/html-self-closing": [
      "error",
      {
        html: {
          void: "always",
          normal: "never",
          component: "always"
        },
        svg: "always",
        math: "always"
      }
    ]
  },
  ignorePatterns: ["*.sh", "node_modules", "*.md", "*.woff", "*.ttf", ".vscode", ".idea", "dist", "/public", "/docs", ".husky", ".local", "/bin", "Dockerfile"]
});

安装 prettier

1
npm i -D prettier

在 .eslintrc.js 文件中添加对 prettier 的配置

1
2
3
4
5
6
7
8
9
const { defineConfig } = require("eslint-define-config");
module.exports = defineConfig({
  extends: [
    // extends 指定扩展的配置, 支持规则的覆盖和聚合
    // ...
    "prettier",
    "plugin:prettier/recommended" // 如果同时使用了eslint和prettier发生冲突了，会关闭掉与prettier有冲突的规则，也就是使用prettier认为对的规则
  ]
});

增加 .prettierrc.js 配置文件， 设定代码格式化的规则

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
module.exports = {
  printWidth: 160,
  tabWidth: 2,
  useTabs: false,
  semi: true,
  eslintIntegration: true,
  vueIndentScriptAndStyle: false,
  singleQuote: false,
  endOfLine: "auto",
  quoteProps: "as-needed",
  bracketSpacing: true,
  trailingComma: "none",
  jsxBracketSameLine: false,
  jsxSingleQuote: false,
  arrowParens: "avoid",
  insertPragma: false,
  requirePragma: false,
  proseWrap: "never",
  htmlWhitespaceSensitivity: "ignore",
  endOfLine: "auto"
};

新建 .prettierignore 忽略文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
.DS_Store
node_modules/
dist/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
**/*.log

# Editor directories and files
.idea
.vscode
.hbuilder
.webstorm
*.suo
*.ntvs*
*.njsproj
*.sln
*.local

package-lock.json
yarn.lock

配置 pre-commit

githooks

Git Hook执行时机说明
pre-commitgit commit 执行前可以用 git commit –no-verify 绕过
commit-msggit commit 执行前可以用 git commit –no-verify 绕过

安装 husky

1
npm i -D husky lint-staged
插件作用
husky提供 git 钩子的解决方案，它可以提供 git 在多个阶段前的操作，比如 pre-commit、pre-push 等，这里我们使用 pre-commit
lint-staged只对 git 暂存区的文件执行 linter 检测，相对每次执行 lint 命令，这种只对增量修改的检测效率会高很多

初始化 husky

1
npx husky install .husky

安装 commitlint

1
npm install -D @commitlint/config-conventional @commitlint/cli

生成配置文件 commitlint.config.js，当然也可以是 .commitlintrc.js

1
echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commitlint.config.js
1
2
3
4
5
6
7
8
// commitlint.config.js
module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "type-enum": [2, "always", ["feat", "fix", "docs", "style", "refactor", "test", "revert"]],
    "references-empty": [2, "never"]
  }
};

在 package.json 中添加如下脚本

1
2
3
4
5
6
7
8
9
10
11
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -e $HUSKY_GIT_PARAMS" // 在husky的配置加入CommitlIint配置，v1.0.1版本以后为HUSKY_GIT_PARAMS，v0.14.3为GIT_PARAMS
    }
  },
  "lint-staged": {
    "*.{js,jsx}": ["eslint --fix", "git add"]
  }
}

现在每次在提交的代码的时候，会默认执行 pre-commit，然后执行 lint-staged 检测，在 lint-staged 脚本中先执行 eslint –fix，如前所述，此时会使用 prettier 规则格式化文件，没有错误会执行 git add 把 fix 过后的文件添加到暂存区，否则会报错退出。

添加一个 commit msg 钩子

1
npx husky add .husky/commit-msg "node scripts/verifyCommit.js"

pre-commit lint

在 commit-msg 执行的时候我们还可以用代码执行之前的钩子，pre-commit，去执行 ESLint 代码格式,
这样我们在执行 git commit 的时候，首先会进行 ESLint 校验，然后在执行 commit 的 log 信息格式检查，全部通过后代码才能提交至 Git。

1
npx husky add .husky/pre-commit "npm run lint"

package.json 中创建

1
2
3
4
5
6
{
  "scripts": {
    // ...
    "lint": "eslint --fix --ext .js,vue src/"
  }
}

commit msg

提交格式：<type>: <subject>（注意冒号后面有空格）

1
2
git commit -m 'feat: 增加 xxx 功能'
git commit -m 'bug: 修复 xxx 功能'
typesubject
feat引入新功能
fix修复 bug
style更新 UI 样式文按键
format格式化代码
docs添加/更新文档
perf提高性能/优化
refactor改进代码结构/代码格式
test增加测试代码
build构建过程或辅助工具的变动
ci修改 CI/CD 相关内容
chore日常改动维护
revert还原修改记录

约定式提交 git cz

安装 commitizen

1
npm install commitizen

package.json 配置命令

1
2
3
4
5
6
7
{
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  }
}

项目根目录下创建 .cz-config.js 自定义提示文件

这里的 types 与 vscode 中的类型保持一致

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
module.exports = {
  scopes: [{ name: "mobile" }, { name: "web" }, { name: "shared" }],
  messages: {
    type: "选择要提交的类型(必选):",
    scope: "\nEnlighten us with the scope (optional):",
    customScope: "Add the scope of your liking:",
    subject: "简要描述提交内容(必选):\n",
    body: "注意事项详细描述:\n",
    breaking: "List any BREAKING CHANGES (optional):\n",
    footer: "List any ISSUES CLOSED by this change (optional). E.g.: #31, #34:\n",
    confirmCommit: "确定?"
  },
  types: [
    { value: "feat", emoji: "✨", name: "✨ feat: 引入新功能" },
    { value: "fix", emoji: "🐛", name: "🐛 fix: 修复 bug" },
    { value: "style", emoji: "💄", name: "💄 style: 更新 UI 样式文按键" },
    { value: "format", emoji: "🥚", name: "🥚 format: 格式化代码" },
    { value: "docs", emoji: "📝", name: "📝 docs: 添加/更新文档" },
    { value: "perf", emoji: "👌", name: "👌 perf: 提高性能/优化" },
    {
      value: "refactor",
      emoji: "🎨",
      name: "🎨 refactor: 改进代码结构/代码格式"
    },
    { value: "test", emoji: "✅", name: "✅ test: 增加测试代码" },
    {
      value: "build",
      emoji: "👷",
      name: "👷 build: 构建过程或辅助工具的变动"
    },
    { value: "ci", emoji: "💻", name: "💻 ci: 修改CI/CD相关内容" },
    { value: "chore", emoji: "🔧", name: "🔧 chore: 日常改动维护" },
    { value: "revert", emoji: "⏪", name: "⏪ revert: 还原修改记录" }
  ],
  allowTicketNumber: false,
  isTicketNumberRequired: false,
  ticketNumberPrefix: "#",
  ticketNumberRegExp: "\\d{1,5}",
  allowCustomScopes: false,
  allowBreakingChanges: ["feat", "fix", "chore"],
  breakingPrefix: "🚧 BREAKING CHANGES 🚧",
  footerPrefix: "CLOSES ISSUE:",
  subjectLimit: 100,
  skipQuestions: ["scope", "customScope", "breaking", "footer"]
};

vscode

使用 vscode 开发的同学可以安装扩展 Git CZ Emoji