前端代码规范最佳实践(从0到1全攻略)


【明确目标】

本文提供一套完整的配置方案(支持 vscode + webstorm),配置后:

1、开发者编写代码过程中,会实时红线提示不符合 eslint 规范的代码

2、按下保存(command+s)代码自动按照 eslint 的规则进行格式化,不会发生规范检查(eslint)与自动格式化(prettier)冲突的情况

3、git 提交前,再次自动进行代码规范检查,确保提交到远程仓库的代码符合规范约定


【附】

这里为您提供一个实现了上述 目标,可直接使用的、一键生成规范配置的小工具:feflow-plugin-lint

欢迎使用,欢迎吐槽,我会努力优化哒!


第一部分:编辑器层面的准备工作

一、vscode

1、插件安装(3个)

eslint:让代码不符合约定规范时,能有红线提示

prettier:使得开发者使用快捷键(mac: shift+option+f,windows: shift+alt+f)格式化代码时,可以选择,根据 prettier 的规则来格式化(也就是,使用 prettier 作为 formatter)

editorconfig:读取 .editorconfig 规定的代码格式规范,覆盖掉当前编辑器的自定义配置。使得协作开发中,所有开发者的代码,都遵循 .editorconfig 的规范


2、配置 settings.json

配置方式如下:

编辑内容如下:

// 指定各类文件格式化默认用的 formatter,按需指定(这里可以指定prettier,是因为提前安装了prettier插件)

"[html]": {

    "editor.defaultFormatter": "esbenp.prettier-vscode",

  },

  "[css]": {

    "editor.defaultFormatter": "esbenp.prettier-vscode",

  },

  "[javascript]": {

      "editor.defaultFormatter": "esbenp.prettier-vscode"

  },

  "[json]": {

    "editor.defaultFormatter": "esbenp.prettier-vscode"

 },

"[vue]": {   

     "editor.defaultFormatter": "esbenp.prettier-vscode" 

 }, 

 "[javascriptreact]": { 

    "editor.defaultFormatter": "esbenp.prettier-vscode" 

  },   

"[typescriptreact]": {

    "editor.defaultFormatter": "esbenp.prettier-vscode"

},


也可以直接指定所有文件的默认 formatter(我们这里不建议这样做,原因后文会有说明):

"editor.defaultFormatter": "esbenp.prettier-vscode"


3、测试能力(下面操作,均以 mac 系统为例)

新建一个 js 文件,写一句反规范的测试代码:

按下 shift + options + f:

可以看到,这个时候,prettier 插件,已经帮助我们完成了代码的格式化。

它按照自己默认的那一套规则,格式化了我们的代码。比如使用双引号、加分号。

4、开启保存代码自动格式化

settings.json 添加一句话:

"editor.formatOnSave": true

编辑代码,保存,代码就会按照 prettier 的默认规则进行格式化


至此,vscode 已经初步具备自动规范代码的能力。

但注意,它还不能对不规范的代码进行红线提示。这是 eslint 的能力,也需要项目层面的配置。

如果你使用的就是 vscode,可以直接跳到第二部分,去看项目层面要做的事。

接下来,我们看一下,webstorm 的使用者需要做哪些准备。



二、webstorm

webstorm 这种强大的 IDE,通常不需要我们做什么配置,直接内置了各种能力。但是也因为如此,很多对我们黑盒的东西,常常一知半解,稀里糊涂。

这里,我们先用上面的小例子,直接测试一下 webstorm 的自动格式化效果。

下面操作,均以 mac 系统为例。

格式化之前:

按下 option + command + L:

不知道你们的效果如何,反正,我这里就是没反应。。。

网查了半天,都说是快捷键冲突。但是按我的理解,有冲突,该有提示才对。

虽然不知道是和谁冲突了,索性设置一个自定义的格式化快捷键,再试吧。

设置方式如下:

这里,我把代码格式化快捷键,设置成了 shift + space。

设置完,没有冲突,ok 确认即可。


回到 index.js,按下 shift + space 测试一下:

可以看到,webstorm 默认,仅仅是帮我们整理了缩进。其他代码格式并未改变。

【注意】

这里,使用 webstorm 快捷键格式化,使用的规则,是在 webstorm 编辑器内部定义的。

开发者也可以自行修改这个规则。它根据不同的语言分类,为开发者提供了灵活的配置项:

但是,但是,但是

请注意。

这个配置是编辑器层面的,不同开发者之间,无法共享一套规范。

如果团队某成员使用了自己本地编辑器、自定义了规范,就会和其他成员的代码格式出现差异化。

所以我建议,不要使用这个规则去格式化你的代码!

为了团队协作考虑,请使用下面的方式,去格式化


【让webstorm和vscode一样,使用prettier默认规则格式化】

1、项目层面,安装 prettier

yarn add prettier -D

【注】

webstorm 的 prettier 配置依赖本地的 prettier 可执行文件。

而这种配置,理应属于项目层面,安装到全局并不合适。因此,这里需要混入一步项目层面的操作。

2、配置 webstorm

webstorm -> Preferences

搜索 file watcher,单击➕ 添加:

选择 Prettier:

这里设置成 Any,其他默认即可。更改后点击 OK:

【注】

顾名思义,大家应该看出来了。这里设置的,是一个 Prettier 的文件监听器。

监听什么呢?监听文件的变动,并,在文件变动时,使用 Prettier 默认的规则,对文件进行格式化。

说人话就是,这样设置之后,command + s 保存,代码会按照我们想要的、Prettier 的默认规则,自动格式化代码


3、使用测试

回到 index.js,进行任意编辑、并按下 command + s:

ok,一切符合预期~


【第一部分总结】

完成第一部分,我们目前达到的效果是,两个编辑器,均可以在保存的时候,自动格式化代码。

请注意,这里,html、css、js、json 四类文件可以被自动格式化。(参考 settings.json 的 editor.defaultFormatter 配置)

并且,它们均使用了 Prettier 默认的那套规则。




第二部分:项目层面的配置

1、editorconfig 配置

(1)项目根目录下创建 .editorconfig

root = true

[*]

charset = utf-8

indent_style = space

indent_size = 2

end_of_line = lf

insert_final_newline = true

trim_trailing_whitespace = true

如果你还想进行更多的配置,可以参照官网:https://editorconfig.org/

【.editorconfig 作用解析】

编辑器配置。用于覆盖编辑器默认配置,以确保不同编辑器之间,代码格式的统一。

比如,使用 editorconfig,规定开发过程中,点击 tab 按钮,是以 tab 格式进行缩进,还是以 space 格式进行缩进。

如果没有约定,不同的编辑器,或者相同编辑器、不同开发者的配置存在差异,可能出现,有的人是 tab 缩进、有的人是 space 缩进的情况,造成代码风格的差异。


(2)使用测试

编辑 .editorconfig,设置 indent_size = 4。

分别用 vscode、webstorm 打开刚刚的 index.js,随意编辑,再次格式化(mac: shift+option+f,windows: shift+alt+f):

vscode效果


webstorm效果

可以看到,Prettier 均按照 .editorconfig 的约定,对代码进行了格式化。

也就是说,这里,.editorconfig 的规则,覆盖掉了 Prettier 的默认规则。

同时,在这个规则下,当你编码过程中按下 tab 键,也会默认进行 4 格的缩进。


2、eslint 配置

【eslint 作用解析】

在代码编写的过程中,出现不符合规范的代码,进行红线提示。帮助开发者及时更正不符合规范的代码。

同时,提供命令行检查规范及 auto-fix 能力。

【注】

这里仅给出极简版最佳配置。如当前配置不符合项目需求,或期望了解更多,可以参考:

前端代码规范最佳实践:eslint+prettier+editorconfig+lint-staged 及 贴心的 eslint 各配置项详解


(1)安装 eslint + prettier + eslint-config-prettier + eslint-plugin-prettier

yarn add eslint prettier eslint-config-prettier eslint-plugin-prettier -D


(2)创建 .eslintrc.js

module.exports = {

  root: true,

  env: {

    browser: true,

    es6: true,

    node: true,

  },

  extends: ['eslint:recommended', 'plugin:prettier/recommended'],

  parserOptions: {

    ecmaVersion: 2020,

    sourceType: "module",

  },

};


(3)观察效果

【vscode】

不符合规范的代码,出现红线提示


【webstorm】

没有出现红线提示

【配置 webstorm,把红线搞出来~】

再来看下 webstorm 的效果:

红线成功出现~(*^▽^*)


(4)点击保存(mac: command+s,windows: ctrl+s)

代码自动格式化(按照 .eslintrc 配置的规则):



3、添加 lint-staged

【lint-staged 作用解析】

配合 husky 使用,在代码提交 git 前,进行规范性检查或格式化。如果代码不符合规范,则阻止提交。确保提交到 git 仓库的代码质量。


(1)安装husky + lint-staged 

yarn add husky lint-staged 


(2)配置 package.json

{

    "scripts": {

        "lint": "eslint .",

        "prettier": "prettier --write ."

    }

    "husky": {

        "hooks": {

          "pre-commit": "lint-staged"

        }

      },

  "lint-staged": {

        // 这里的匹配规则,按需自定义。比如,检查 js + vue,可以这样:"*.{js, vue}"。详见:https://github.com/okonet/lint-staged

        "*.js": [

          "npm run prettier",

          "npm run lint",

          "git add ."

        ]

  }

}


(3)配置 .eslintignore + .prettierignore + .gitignore

.eslintignore、.prettierignore 内容相同。一般需要忽略以下这些文件:

.DS_Store

node_modules

dist


# local env files

.env.local

.env.*.local

# Log files

npm-debug.log*

yarn-debug.log*

yarn-error.log*

# Editor directories and files

.idea

.vscode

*.suo

*.ntvs*

*.njsproj

*.sln

*.sw?

.gitignore 参考如下:

.DS_Store

node_modules

dist


# local env files

.env.local

.env.*.local

# Log files

npm-debug.log*

yarn-debug.log*

yarn-error.log*

# Editor directories and files

.idea

.vscode

*.suo

*.ntvs*

*.njsproj

*.sln

*.sw?


(4)观察效果

执行 git commit:

可以看到形如上面截图的报错。这是自动执行 prettier 格式化后,再执行 eslint 检查,仍然存在的代码规范错误。这类错误,就需要开发者手动进行处理了~

修改代码:

再次执行 commit 试试:

提交成功。


【阶段性成果总结】

至此,我们达成了以下这些能力:

(1)保存代码,任意代码都能够自动按照统一的规则(.editorconfig覆盖prettier默认规则得到的规则)进行格式化

(2)开发过程中,如果有书写不规范的代码,eslint 能够即时给出红线提示

(3)使用 git 提交代码时,会再次对所有 .prettierignore 以外的代码进行自动的 prettier 格式化

(这一步,是为了防止团队成员、自己本地未进行编辑器支持 prettier 的配置)

格式化后,再次进行自动的 eslint 规范性检查,检查通过,才允许提交。否则,进行错误提示

(这一步,是为了检查出 prettier 不能够自动修复的规范问题。如:变量定义但未使用)


4、自定义代码规范

默认的规则,必然会存在一些不符合我们开发习惯的情况。因此,自定义规范,必然是刚需。

(1)创建.prettierrc

{

  "singleQuote": true

}

前面可以看到,Prettier 默认的规则是,使用双引号。这里,我们要求字符串使用单引号。


(2)效果测试

配置后,打开 index.js,任意编辑后,点击保存:

【注】

项目目录下的 .prettierrc 文件,具有格式化规则的最高优先级,它会覆盖掉默认的 prettier 规则以及 .editorconfig 的规则。


【总结】

至此,我们完成了基于 eslint:recommended 规范的 eslint 检查 + prettier 格式化配置。

这套配置能够强有力地保证团队协作中的代码规范性,同时,兼容 vscode、webstorm 两大编辑器。

具体能力如下,再次列举:

(1)保存代码,任意代码都能够自动按照统一的规则进行格式化

(统一的规则:.eslintrc 中配置的 rules。即:editorconfig覆盖 prettier 默认规则、.prettierrc 覆盖.editorconfig,得到的规则)

(2)开发过程中,如果有书写不规范的代码,eslint 能够即时给出红线提示

(3)使用 git 提交代码时,会对所有 .prettierignore 以外的代码进行自动的 prettier 格式化

(这一步,是为了防止团队成员、自己本地未进行编辑器支持 prettier 的配置)

格式化后,再次进行自动的 eslint 规范性检查,检查通过,才允许提交。否则,进行错误提示

(这一步,是为了检查出 prettier 不能够自动修复的规范问题。如:变量定义但未使用)





第三部分:以 vue 项目为例,配置实际项目

1、安装  eslint-plugin-vue

yarn add eslint-plugin-vue -D

2、配置 .eslintrc.js

添加 'plugin:vue/essential':

给 eslint 添加 vue 插件,是为了让 eslint 认识 vue 的语法,并按照 vue/essential 这套规则,进行检查。

3、创建任意 vue 文件,编写不符合规范的代码,观察效果。这里不再演示。



【后记】

关于 eslint、prettier、editorconfig 以及 eslint-config-prettier、eslint-plugin-prettier 的作用与能力讲解,

可以参考:前端代码规范最佳实践:eslint+prettier+editorconfig+lint-staged

你可能感兴趣的:(前端代码规范最佳实践(从0到1全攻略))