Lucas's Blog
HomeArchiveTagsCategoriesAboutLabPitfallDocs

统一前端编码规范和相关工具

发表于 2022/03/15前端工程化🍵 ≈ 6 mins

编码规范

以我们团队的项目为例，整体是从以下几个方面约定编码规范：

当然还有其他方面的编码规范，比如 vue、JSON 等等

以上规范只是说提供一套规范依据（可以协助 code review），团队在开发的过程中要尽可能遵循（当然可以提出自己的修改意见），然后在实践过程中渐渐形成自己的一套规范，并不断去完善这一套规范

这些编码规范都可以借助一些第三方插件来辅助落实。编辑器建议用 vscode，然后在本地可以借助 vscode 插件来约束代码（可以让我们在编写代码时实时发现一些语法问题，以及保存时自动格式化代码）

辅助工具

eslint

针对 js/ts/react/vue/... 代码进行语法检查和错误预警，减少一些低级错误；同时也能提高 code review 的效率。注意 eslint 不做代码格式规范

yarn add eslint -D
yarn eslint --init

.eslintrc.js 推荐配置：

module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true,
    jest: true,
  },
  extends: [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "plugin:@typescript-eslint/recommended",
  ],
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaFeatures: {
      jsx: true,
    },
    ecmaVersion: "latest",
    sourceType: "module",
  },
  plugins: ["react", "@typescript-eslint"],
  rules: {
    "no-var-requires": 0,
  },
};

然后记得在 vscode 中安装 eslint 插件

eslint 详细配置参考 https://eslint.org/docs/user-guide/configuring/

stylelint

类似于 eslint，stylelint 可以帮助检查和修复 css/less/scss 等样式的代码

yarn add stylelint stylelint-config-standard -D

项目根目录下新增 .stylelintrc.js

module.exports = {
  extends: "stylelint-config-standard",
  rules: {}, // 自定义规则
};

然后记得在 vscode 中安装 stylelint 插件

prettier

统一代码格式，包括 js/ts/css/less/...，可以让团队代码形成一种统一的风格，提高代码可读性，也便于多人开发协作

yarn add prettier -D

.prettierrc.js 推荐配置：

module.exports = {
  printWidth: 160, //编辑器每行的长度，默认80
  tabWidth: 4, //制表符tab的宽度，默认值是2
  useTabs: false, //代码缩进是否用制表符tab，默认false
  semi: true, //是否使用分号，默认true，使用分号
  singleQuote: true, //是否使用单引号，默认为false
  quoteProps: "as-needed", //对象属性的引号使用 as-needed 仅在需要的时候使用 consistent 有一个属性需要引号，就都需要引号 preserve 保留用户输入的情况
  jsxSingleQuote: false,
  trailingComma: "none", //末尾逗号 none 末尾没有逗号 es5 es5有效的地方保留 all 在可能的地方都加上逗号
  bracketSpacing: true, //字面量对象括号中的空格，默认true true - Example: { foo: bar }.  false - Example: {foo: bar}.
  jsxBracketSameLine: false,
  arrowParens: "avoid", //箭头函数中的括号always avoid
  htmlWhitespaceSensitivity: "ignore",
  vueIndentScriptAndStyle: false, //是否给vue中的 <script> and <style>标签加缩进
  endOfLine: "auto", //行末尾标识
  eslintIntegration: true, //不让prettier使用eslint的代码格式进行校验
};

需要安装 vscode 的 prettier 插件，然后可以选择开启保存时自动格式化代码的功能

prettier 详细配置参考 https://prettier.io/docs/en/configuration.html

EditorConfig

使用不同编辑器打开同一份文件，如果编辑器配置不统一，显示效果和输入内容很有可能不一致。EditorConfig 就主要用于统一代码编辑器编码风格

.editorConfig 配置文件参考

# https://editorconfig.org

# 已经是顶层配置文件，不必继续向上搜索
root = true

[*]
# 编码字符集
charset = utf-8
# 缩进风格是空格
indent_style = space
# 一个缩进占用两个空格，因没有设置tab_with，一个Tab占用2列
indent_size = 2
# 换行符 lf
end_of_line = lf
# 文件以一个空白行结尾
insert_final_newline = true
# 去除行首的任意空白字符
trim_trailing_whitespace = true

[*.md]
insert_final_newline = false
trim_trailing_whitespace = false

详细配置参考 https://editorconfig.org/

commitlint

commitlint 用于检测 commit message 是否合法。message 的格式如下：

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
  1. 标题行（subject）: 必填, 描述主要修改类型和内容
  2. 主题内容（body）: 描述为什么修改, 做了什么样的修改 以及开发的思路等等。
  3. 页脚注释（footer）: 可以写注释，放 BUG 号的链接。=

type 类型约定如下：

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

配置方式在下一节 Husky 中提及

Husky

Husky 是一个操作 git 钩子的工具，可以做代码提交检测，阻止不规范的代码提交和推送。注意：husky 要求 git 版本 > 2.13.0

lint-stage 是一个本地暂存代码检查工具，可以让 husky 只检验 git 工作区的文件

  1. 安装依赖，包括 commitlint 相关依赖
npm i husky lint-stage -D
npm i @commitlint/cli @commitlint/config-conventional -D
  1. 在 package.json 追加配置
"scripts": {
  //...
  "prepare": "husky install",
  "precommit": "eslint src/**/*.js"
},
"lint-staged": {
  "src/**/*.{js,jsx,ts,tsx}": [
    "prettier --write",
    "eslint --cache --fix",
    "git add"
  ]
},
  1. 配置 commitlint 规则（commitlint.config.js）：
module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: {}, // 自定义规则
};
  1. 初始化 husky
yarn prepare
# 这个命令在 yarn 安装依赖后会自动执行
  1. 然后执行以下命令，会自动在生成的 .husky 文件夹下新建两个钩子文件 commit-msg 和 pre-commit
npx husky add .husky/commit-msg 'yarn commitlint --edit "$1"'
npx husky add .husky/pre-commit 'yarn lint-staged'

文件内容如下（确保自动生成的文件内容跟以下的保持一致）：

  • commit-msg
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

echo "========= 校验 commit-msg ======="
yarn commitlint --edit $1
  • pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

echo "========= 执行 lint-staged ======="
yarn lint-staged

注意：以上脚本执行的路径要确保与 .git 同级，不同级可以参考 https://blog.zhouweibin.top/FEED/create-react-app/#git扩展-9 提供的解决方法

配置好 eslint/stylelint/prettier 后，在 package.json 中配置对应的 script 命令便于全局检查和格式化项目代码

"scripts": {
    "eslint": "eslint --fix src/**/*.{js,ts,jsx,tsx}",
    "stylelint": "stylelint --fix src/**/*.{css,less}",
    "prettier": "prettier --write src/**/*.{js,ts,jsx,tsx,less,css}"
}

其他工具

  • commitlizen。以命令行交互的方式协助输入 commit 信息

备注

以上工具均需要在项目中增加额外的依赖和配置文件，更好的方式是通过定制脚手架的方式快速安装依赖和生成配置文件，提供开箱即用的项目模板

编码规范eslintprettierstylelint