eslint+prettier+husky+lint-staged 统一前端代码规范

时间:2024-03-02 15:33:03

eslint+prettier+husky+lint-staged 统一前端代码规范

遵循编码规范和使用语法检测,可以很好的提高代码的可读性,可维护性,并有效的减少一些编码错误。

1、终极目标

团队中的所有开发人员用一套代码规范规则,并且无需我们花太大的精力去为了格式而格式。希望有一套自动化工具,帮我们检测代码是否规范,如果不规范,则自动能够帮我们按照既定规范格式化。

实现这一目标需解决的问题:

1、代码规范落地难:面对开发规范经常面临的现状是很难落地,总是“拆东墙补西墙”,归根结底在于需要工具去强行保证代码必须经过代码开发规范的扫描;

2、低质量代码带入线上应用:在开发现状中开发人员可以简单的执行git push操作将本地代码带入远程分支上,如果代码质量低下就很容易对线上应用质量埋下隐患,最好的方式本地进行commit的时候,最起码需要保证当前代码能够满足团队制定的开发规范,如果不通过,commit都无法成功,这样能够从最源头保证代码质量;

3、代码格式难统一:现状团队开发成员代码格式都有很大的不同,有些人字符串喜欢用双引号,有的人喜欢使用单引号等等问题,如果代码格式化问题不统一,互相查看其它人代码很累,甚至代码格式错乱,严重影响代码可读性,无疑也增加了团队内的沟通成本,针对这样情况,需要一种工具能够保证团队内代码的格式是一致;

4、代码质量文化难落地:过引入代码质量工具,在开发过程中能够时刻对自身代码质量进行约束,逐渐培养自身对代码质量有“洁癖”的开发观念,同时也会成为团队乃至自身对质量文化落地的一个抓手;

面对以上问题,eslint+prettier+husky+lint-staged 这几个工具能够有效解决上述问题。

2、eslint 配置

ESLint 是一个Javascript Linter,帮助我们规范代码质量,提高团队开发效率。

避免代码错误、写出最佳实践、规范变量使用方式、规范代码格式;

社区比较知名的代码规范,eslint 配合这些代码规范,能够检测出代码潜在问题,从而提高代码质量。

官方提供了3种规范:

eslint-config-google:Google标准

eslint-config-airbnb:Airbnb标准,它依赖eslint, eslint-plugin-import, eslint-plugin-react, and eslint-plugin-jsx-a11y等插件,并且对各个插件的版本有所要求

eslint-config-standard:Standard标准,它是一些前端工程师自定的标准,

目前来看,公认的最好的标准是Airbnb标准。

2.1 默认配置

使用 Create React App 创建的 React 应用,默认安装了ESLint依赖,package.json文件中的 eslintConfig 属性只提供了用于发现常见错误的最小规则集。

 "eslintConfig": {
       "extends": "react-app"
  }

2.2 自定义配置

2.2.1 在根目录下创建 .eslintrc.json 文件,完成一些基础配置,代码如下:
{
   // env:你的脚本将要运行在什么环境中
   "env": {
       "browser": true,
       "es6": true,
       "jquery":true
  },
   // globals:脚本在执行期间访问的额外的全局变量
   "globals": {
       "$": true,
       "process": true,
       "__dirname": true
  },
   // 指定ESLint使用的解析器,默认是Espree
   "parser": "babel-eslint",
    // 指定想要支持的 JavaScript 语言选项
   "parserOptions": {
       "ecmaFeatures": {
           "experimentalObjectRestSpread": true,
           "jsx": true,
           "modules": true
      },
       "sourceType": "module",
       "ecmaVersion": 7
  },
    //让eslint支持 JSX start
   "plugins": ["react"],
   // 继承已启用的规则
   "extends": ["eslint:recommended"],
   // 启用的规则及其各自的错误级别。自定义启用或关闭一些规则
   "rules": {
       "react/jsx-uses-react": 1,
       "no-unused-vars": 0, //变量声明未被使用校验
       "no-empty": 0,
       "quotes": 0, //单引号
       "no-console": 0 //不禁用console
  }
}

想具体了解各个配置什么意思的,请参考官网:http://eslint.cn/docs/user-guide/configuring

2.2.2 配置完成,测试效果

完成上述配置之后,只会影响编辑器和 IDE 检测与规则不符的代码(比如在vscode中与规则不符的代码有红色的下划波浪线),不会在控制台和浏览器中出现相关提示。

image-20200730155438109

2.3 扩展 ESLint 配置

因我们项目使用react-app-rewired 对 Create React App 进行了自定义配置,所以需要修改config-overrides.js,修改后的代码如下:

const { override, fixBabelImports, addWebpackAlias,useEslintRc } = require('customize-cra')
const path = require('path')

//重写配置
module.exports = override(
 // 配置路径别名
 addWebpackAlias({
   '@': path.resolve(__dirname, 'src')
}),
 // antd按需加载
 fixBabelImports('import', {
   libraryName: 'antd',
   libraryDirectory: 'es',
   style: 'css'
}),
 //启用eslintrc配置文件
 useEslintRc()
)

经过上述配置后,eslint 生效,npm start 会在控制台和浏览器中出现相关错误提示:

控制台报错:

image-20200730161551116

浏览器报错:

image-20200730162908826

2.4 忽略特定的文件或目录

在项目根目录创建一个 .eslintignore 文件告诉 ESLint 去忽略特定的文件和目录。.eslintignore 文件是一个纯文本文件,其中的每一行都是一个 glob 模式表明哪些路径应该忽略检测。例如:

build/*.js
public
dist
node_modules
config
config-overrides.js
src/serviceWorker.js
prettierrc
.DS_Store
.eslintrc.json
node_modules

2.5 eslint fix自动修复

eslint --fix 可以根据规范对代码的部分低级问题进行更正,如:缺少/多余分号,缩进格式等。

能够修复的规范问题比较有限,需要较大变动才能修复的规范问题,eslint 无法自动修复。如:单行不能超过 80 个字符。

自动修复src文件夹下.js文件和.jsx文件部分规范问题,命令如下:

eslint --fix --ext .js --ext .jsx src/

3、eslint集成prettier

prettier 是一个「武断的」(官网用词: opinionated )代码格式化工具。(只关心代码格式,统一代码风格)

根据规范,自动格式化代码,具有比 eslint auto-fix 更加强大的代码规范性修复能力。

官网:https://prettier.io/

3.1 安装prettier

根据 prettier官方建议,Prettier 版本升级后可能会有风格变化,故应当锁定 Prettier 的版本号。

npm install prettier --save-dev

3.2 安装eslint-plugin-prettier

ESLint插件,eslint-plugin-prettier 作为一个 ESLint的规则运行,并报告不同的单个ESLint问题。

将 prettier 的能力集成到 eslint 中。按照 prettier 的规则检查代码规范性,并进行修复。

npm install eslint-plugin-prettier --save-dev

修改.eslintrc.json文件:

第一种方式:

//插件增加prettier
"plugins": ["react","prettier"],
//继承规则增加prettier
"extends": ["eslint:recommended","prettier"],
// 不符合 prettier 规则的代码,要进行错误提示(红线)
"rules":{
 "prettier/prettier":"error"
},

第二种方式:

//相当于上面三个操作
{
   "extends": ["eslint:recommended","plugin:prettier/recommended"]
}

注:extends的含义

告诉 eslint,根据指定的规范,去检查指定类型的文件。如上例:

根据 eslint:recommended + prettier 规范,去检查 js 代码。

当某一类型的文件,被制定了不止1个规范,存在某些规范冲突时,后面的会覆盖掉前面的。

3.3 安装eslint-config-prettier解决冲突(如果存在冲突)

npm install  eslint-config-prettier --save-dev

作用:解决冲突,让所有可能会与 prettier 规则存在冲突的 eslint rule 失效,并使用 prettier 的规则进行代码检查。相当于用 prettier 的规则,覆盖掉 eslint:recommended 的部分规则。

后面 prettier 格式化,也会根据这个规则来。因此,不会再有冲突。

3.4 prettier自动格式化

自动格式化src目录下的文件,命令如下:

prettier --write 'src/**/*.{js,css,jsx,html}'

3.5 自定义配置

根目录下新建.prettierrc文件,可根据需要进行一些自定义配置,示例如下:

{
  "printWidth": 100,
  "singleQuote": true,
  "trailingComma": "es5",
  "tabWidth": 4,
  "semi": true,
  "jsxBracketSameLine": false,
  "jsxSingleQuote": true,
  "useTabs": false
}

【注】这里的 .prettierrc,具有格式化规则的最高优先级。

3.6 忽略特定的文件或目录

在根目录下新建.prettierignore文件,直接添加文件名和目录名,与.eslintignore类似,示例如下:

build/*.js
public
dist
node_modules
config
config-overrides.js
src/serviceWorker.js
prettierrc
.DS_Store
.eslintrc.json
node_modules

prettier格式化的时候会忽略该配置文件中的文件或目录

4、编辑器自动格式化代码

4.1 使用编辑器快捷键,格式化代码

以 vscode 为例:shift + option + f,默认格式化规则选择 prettier,即可完成代码格式化。

4.2 保存代码自动格式化

同样以 vscode 为例,打开你的 settings.json,添加下面这句话:

"editor.formatOnSave": true

至此jsx,js、json、scss等文件,均可实现自动格式化。文件格式化规则,遵从我们在 .eslintrc.json 里的配置。也就是,使用我们的 prettier 插件规则去格式化。

5、规范检查增强(husky + lint-staged)

在 git commit 之前,先强制执行prettier格式化(防止某些成员开发期间不开启编辑器格式化)、再检查代码规范,如果检查不通过、阻止提交。

5.1 安装 husky

npm install husky --save-dev

husky: git hook工具。这里主要用它防止不规范代码被commit、push、merge等等。

5.2 安装 lint-staged

npm install lint-staged --save-dev

Lint-staged提供了一个关键的功能,它能找到所有被git staged的文件,而不是工程下面所有的文件,然后通过管道交给Prettier做格式化。

5.3 配置husky和lint-staged

在package.json新增配置,如下:

    "husky": {
       "hooks": {
           "pre-commit": "lint-staged"
      }
  },
   "lint-staged": {
       "*.{js,jsx}": [
           "prettier --write",
           "eslint",
           "git add ."
      ]
  },

precommit由Husky处理,它会依照配置在把代码提交到仓库前运行lint-staged(也可以配置其他命令)。

Lint-staged再找到属于它自己的配置部分,即lint-staged键下面的配置。

上面的配置,git commit 之前,所有staged状态的,且扩展名是.js和.jsx的文件都会自动使用 prettier 格式化。格式化后,自动检查所有文件,是否全部符合 eslint 规范。

存在不符合规范的代码,git commit 将被终止。

修改代码,进行测试,结果如下:

image-20200731105406379

与预期完全一致,如果有不符合代码规范或语法错误的代码提交不了。输出错误信息,点击可定位到错误位置。

为何一定要用lint-staged?

为什么一定要用lint-staged,用Husky直接调用npm脚本不更简单么。配置如下:

 "scripts": {
       "start": "react-app-rewired start",
       "build": "react-app-rewired build",
       "test": "react-app-rewired test",
       "fix": "eslint --fix --ext .js --ext .jsx src/",
       "format": "prettier --write 'src/**/*.{js,css,jsx,html}'"
  },
 "husky": {
       "hooks": {
           "pre-commit": "npm run format && npm run fix"
      }
  },

如果是这样配置的话,就没有必要用lint-staged了。因为,这样的配置会把prettier,eslint应用到所有匹配.js,.jsx的文件上,而不是仅staged状态的文件。

5.4 husky扩展

5.4.1、单元测试检测

把单元测试加入到预提交检查中,保证只有通过了单元测试才正式提交代码到仓库。

配置如下:

 "husky": {
       "hooks": {
           "pre-commit": "lint-staged && npm test"
      }
  },

只是配上这个命令是不能跑的,还是要集成Jest单元测试框架,编写单元测试代码。

5.4.2、commit messages规范与约束

git每次提交代码,都必须写commit message(提交说明),用来说明本次提交的目的,否则不允许提交。

commit message的写法规范有许多,目前使用最广的,比较合理和系统化的一种规范:Angular 规范。

工具commitizen/cz-cli会产生规范性的提示语句,帮助我们形成规范的commit message。

工具commitlint用于检查我们的commit message是否符合提交规范,如果不符合,则直接拒绝提交。

huskey配置如下:

 "husky": {
   "hooks": {
     "commit-msg": "commitlint -e $GIT_PARAMS"
  }
}

5.5 husky不起作用怎么办

配置完成后 git commit 不起作用。

解决方案:确认 .git/hooks/* 下的文件,删除对应命令的文件,重新执行安装即可。

6、总结

规范仅仅通过人为的培训或者文档来约束,是不可靠的。

能通过工具约束的尽量通过工具约束,而不要依靠默契和口头约定。

通过使用这些工具能够在一定程度上保证应用的质量问题,并能达到事半功倍的效果。

至此我们开头的终极目标已实现~~!

7、引用

https://www.jianshu.com/p/56bee5bf1568

https://www.jianshu.com/p/f0d31f92bfab

https://segmentfault.com/a/1190000009546913

https://www.cnblogs.com/zhoumingjie/p/11582862.html

https://www.cnblogs.com/jiaoshou/p/12222665.html

还有引用其它文章一些内容,不再一一列举了。。。。