前端代码规范最佳实践

Why

团队开发中，每个人的编码习惯不同，代码格式不同。这就会导致代码难看，难以维护。统一代码风格可以：

增强代码的可读性，降低维护成本
有利于代码审查
养成规范代码的习惯，有利于自身成长

How

推荐使用 eslint + prettier 来进行代码格式化。

通过 git hook 调用来实现代码的自动格式化，git hooks 工具推荐 husky。

既然用到了 git hook，顺便把提交信息规范也做一下，这里推荐 commitlint。

用到的插件

eslint: js/jsx 语法检查插件

按照已有配置检查 js/jsx 语法，能抛出错误、警告，并且能修复一部分错误
stylelint: css 样式格式化工具
prettier: 代码格式化插件

按照已有配置进行代码格式化
husky: git hooks 工具

对 git 执行的一些命令，通过对应的 hooks 触发，执行自定义的脚本程序。

比如，我们可以定义pre-commit钩子的脚本为npm run test。这样在代码提交前就会执行npm run test
lint-staged: 在 git 暂存区运行 linters 的工具

只检查暂存区内容，避免每次 lint 执行都针对所有代码

相当于每次只对修改的内容执行 eslint + prettier 格式化
commitlint: 提交信息检查工具
检查提交信息是否符合规范

eslint 7.x

1. 安装

cnpm install eslint -D

2. 使用

配置 eslint
eslint --init添加 eslint 配置文件。然后修改配置，具体配置如下：

module.exports = {
    // 特定项目下，不再检索上级目录
    root: true,
    env: {
        browser: true,
        es6: true,
        node: true,
        amd: true
    },
    extends: [
        'eslint:recommended',
        'plugin:react/recommended',
        // eslint-config-prettier的缩写
        'prettier'
    ],
    plugins: ['react'],
    // 解析器选项
    parserOptions: {
        sourceType: 'module',
        ecmaFeatures: {
            jsx: true
        }
    },
    settings: {
        react: {
            version: 'detect'
        }
    },
    rules: {
        'no-unused-expressions': 'off',
        'no-unused-vars': 'warn',
        'no-debugger': 'error',
        'no-unreachable': 'warn',
        'react/prop-types': 'off'
    }
};

这里，我们用到了几个 eslint 的插件，需要安装：

cnpm install eslint-config-prettier eslint-plugin-react -D

eslint-config-prettier 的作用是使用 Prettier 默认推荐配置，并且关闭 eslint 自身的格式化功能，防止 Prettier 和 ESLint 的自动格式化的冲突

在 package.json 的 scripts 里添加 eslint 脚本命令，如下：

"scripts": {
  // ...
  "eslint": "eslint --ext js,jsx src --fix",
},

值得注意的是，这里我们指定了 src 目录，所以没必要再加.eslintignore文件了。

npm run eslint即可进行 eslint 检查和修复（只能修复部分格式的问题）。

stylelint14.x

1. 安装

cnpm install stylelint -D

2. 配置

创建.stylelintrc.js,增加以下配置：

module.exports = {
  extends: ["stylelint-config-standard-scss", "stylelint-config-prettier"],
  plugins: ["stylelint-order"],
  defaultSeverity: "warning",
  overrides: [],
  rules: {
    "color-no-invalid-hex": true,
    "annotation-no-unknown": true,
    "function-calc-no-unspaced-operator": true,
    "function-no-unknown": true,
    "block-no-empty": true,
    "unit-allowed-list": ["em", "rem", "s", "%", "px", "vw", "vh"],
    "no-duplicate-selectors": true,
    "selector-class-pattern": null,
    "order/properties-order": [
      "position",
      "top",
      "right",
      "bottom",
      "left",
      "z-index",
      "display",
      "justify-content",
      "align-items",
      "float",
      "clear",
      "overflow",
      "overflow-x",
      "overflow-y",
      "margin",
      "margin-top",
      "margin-right",
      "margin-bottom",
      "margin-left",
      "border",
      "border-style",
      "border-width",
      "border-color",
      "border-top",
      "border-top-style",
      "border-top-width",
      "border-top-color",
      "border-right",
      "border-right-style",
      "border-right-width",
      "border-right-color",
      "border-bottom",
      "border-bottom-style",
      "border-bottom-width",
      "border-bottom-color",
      "border-left",
      "border-left-style",
      "border-left-width",
      "border-left-color",
      "border-radius",
      "padding",
      "padding-top",
      "padding-right",
      "padding-bottom",
      "padding-left",
      "width",
      "min-width",
      "max-width",
      "height",
      "min-height",
      "max-height",
      "font-size",
      "font-family",
      "font-weight",
      "text-align",
      "text-justify",
      "text-indent",
      "text-overflow",
      "text-decoration",
      "white-space",
      "color",
      "background",
      "background-position",
      "background-repeat",
      "background-size",
      "background-color",
      "background-clip",
      "opacity",
      "filter",
      "list-style",
      "outline",
      "visibility",
      "box-shadow",
      "text-shadow",
      "resize",
      "transition"
    ]
  }
};

这里, 我们用到了几个插件：

stylelint-config-standard-scss: stylelint 默认规则只能格式化 css，这里我们使用该插件的规则来格式化 scss。

stylelint-config-prettier: 避免 stylelint 与 prettier 冲突的插件。

stylelint-order: 给属性排序的插件。属性会按照 rules 里 order/properties-order 所定义的顺序排序。

此外，我们还要安装stylelint-scss，因为 stylelint 默认是没有格式化 scss 的能力的。

安装：

cnpm install stylelint-scss stylelint-config-standard-scss stylelint-config-prettier stylelint-order -D

在 package.json 的 scripts 里添加 stylelint 脚本命令，如下：

"scripts": {
  // ...
  "stylelint": "stylelint src/**/*.{less,scss,css} --fix",
},

使用npm run stylelint即可对 src 下的样式文件进行格式化。

prettier

1. 安装

cnpm install prettier -D

2. 使用

配置 prettier
创建 prettierrc.js 文件：

echo module.exports = {}>.prettierrc.js

添加配置，这里可以根据自己需要调整风格。比如：

module.exports = {
  printWidth: 120,
  tabWidth: 2,
  useTabs: false,
  semi: true,
  singleQuote: false,
  jsxSingleQuote: true,
  jsxBracketSameLine: true,
  trailingComma: "none",
  bracketSpacing: true
};

最好再加上.prettierignore文件，避免把不必要的文件也进行格式化。

#ignore
node_modules
.DS_Store
yarn*
*-lock*
dist*
public/

prettier --write即可进行 prettier 格式化。

lint-stated 13.x

1. 安装

cnpm install lint-staged -D

2. 使用

在 package.json 里添加 lint-staged 选项

"lint-staged": {
  "**/*.{js,jsx,ts,tsx}": [
    "eslint --fix"
  ],
  "**/*.{js,jsx,ts,tsx,cjs,json,less,scss,css,md}": [
    "prettier --write"
  ],
  "**/*.{less,scss,css}": [
    "stylelint --fix"
  ]
},

在 package.json 的 scripts 里添加 lint-staged 脚本命令

"scripts": {
  // ...
  "lint-staged": "lint-staged"
},

这样，当我们使用npm run lint-staged的时候，就会自动调用 eslint+prettier 格式化。

commitlint

1. 安装

cnpm install --save-dev @commitlint/config-conventional @commitlint/cli

2. 使用

初始化 commitlint 配置文件

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

配置 commitlint
1. 提交信息结构
  通常 commitlint 认为我们提交信息格式如下：

type(scope?): subject
body?
footer?

其中, scope/body/footer 这三个可有可无。

校验规则
一般的校验规则格式如下：

level: 有三个参数。0 代表禁用， 1 代表警告， 2 代表错误
when: 有两个参数。always 代表总是， never 代表从不
value: 参数值
比如：

"subject-empty": [2, "never"],
"body-empty": [2, "always"],
"type-enum": [2, "always", ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'revert']]

就是强制 body 必须为空，subject 不可为空，type 必须是上面数组里的其中一个。不然就报错。

git commit -m "feat: 增加了新功能"
git commit -m "fea: 增加了新功能" // 报错，type 必须为'feat', 'fix', 'docs', 'style', 'refactor', 'test', 'revert'中的一个

更多规则参考官网
https://commitlint.js.org/#/reference-rules

自定义校验规则
如果已有的规则满足不了需求，我们还可以自定义校验规则。自定义校验规则写在 plugins 属性中。

module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "type-empty": [2, "always"],
    "scope-empty": [2, "always"],
    "subject-empty": [2, "always"],
    "header-max-length": [2, "always", 100],
    "body-empty": [2, "always"],
    "footer-empty": [2, "always"],
    "action-enum": [
      2,
      "always",
      ["Fixed", "Feature",  "Add", "Modify", "Update", "Delete"]
    ],
    "issue-rule": [2, "always", ["TMP", "TTT"]] // 根据自己需要输入即可
  },
  plugins: [
    {
      rules: {
        "action-enum": ({ raw }, when = "always", value = []) => {
          return [
            value.includes(raw.split(" ")[0]),
            `提交信息不合规范! {Action}错误!
    必须以 "{Action}{空格}#{标号}{空格}" 开头。
    {Action}可选：${value.join("|")}
    比如: Fixed #TMP-111 修复接口传参错误的问题
    ${when === "never" ? "另外: action-enum规则第二个参数必须是always, 建议修改" : ""}...`
          ];
        },
        "issue-rule": ({ raw }, when, value = []) => {
          const issueStr = `^([A-Z][a-z]*\\s#(${value.join("|")})\\-[1-9][0-9]*)`;
          const issueReg = new RegExp(issueStr, "g");
          return [
            issueReg.test(raw),
            `提交信息不合规范! {标号}错误!
    必须以 "{Action}{空格}#{标号}{空格}" 开头。
    {标号}可选: ${value.join("|")}
    比如: Fixed #TMP-111 修复接口传参错误的问题
    ${when === "never" ? "另外: action-enum规则第二个参数必须是always, 建议修改" : ""}...`
          ];
        }
      }
    }
  ]
};

这里，我把 type, scope, subject, body, footer 都强制为空，然后自定义了两个规则action-enum和issue-rule。

提交代码的时候，如果不符合'必须以 "{Action}{空格}#{标号}{空格}" 开头'的规则，就会报错，提交失败。例如：

git commit -m "Fixed #TMO-222 修复了传参错误的bug"

由于我们定义的标号前缀里面没有 TMO，因此会报错：

husky 8.x

1. 安装

cnpm install husky -D

2. 使用

npm set-script prepare "husky install"
npm run prepare

这里我们在 scripts 加了一个 prepare 命令，这个命令会在执行 npm install 时自动执行。

npx husky add .husky/pre-commit "npm run lint-staged"
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

这里我们添加了两个钩子，pre-commit 与 commit-msg。

pre-commit 会在提交前执行npm run lint-staged命令

commit-msg 会在提交时执行npx --no-install commitlint --edit "$1"

至此，我们的配置完成。代码提交的时候会自动对修改的代码进行格式化，同时会按照 commitlint 里的设置来进行提交信息校验。

如果有问题，则会报错，且代码会提交失败。

vscode 插件

1. eslint 和 prettier 插件

推荐使用 vscode 插件 eslint 和 prettier，可以在 settings.json 中设置：

"editor.formatOnSave": true,
"eslint.run": "onSave"

当我们保存的时候，会自动进行格式化, 会自动把 eslint 的错误语法用波浪线标出来。

2. 把 eslint 和 prettier 插件配置加到项目目录

vscode 的配置分两类，工作区和用户区。工作区的优先级高于用户区。
在项目根目录加上.vscode 文件夹，里面是 settings.json 文件。
那么我们的项目就是一个工作区了。

修改 settings.json 配置如下:

{
  "[javascriptreact]": {
      "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascript]": {
      "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
      "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "editor.formatOnSave": true,
  "eslint.run": "onSave"
}

这样就完成了 vscode 配置的共享。

参考资料：

husky 官方文档

 lint-staged 官方文档

 commitlint 官方网站

 commitlint 从 0 到 1 (git commit 校验工具)

[前端架构师神技，三招统一代码风格（一文讲透）
](https://cloud.tencent.com/dev...)

本文由mdnice多平台发布

前端代码规范最佳实践

Why

How

用到的插件

eslint 7.x

1. 安装

2. 使用

stylelint14.x

1. 安装

2. 配置

prettier

1. 安装

2. 使用

lint-stated 13.x

1. 安装

2. 使用

commitlint

1. 安装

2. 使用

husky 8.x

1. 安装

2. 使用

vscode 插件

1. eslint 和 prettier 插件

2. 把 eslint 和 prettier 插件配置加到项目目录

你可能感兴趣的:(前端)