前端代码规范最佳实践(从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

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 205,132评论 6 478
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 87,802评论 2 381
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 151,566评论 0 338
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 54,858评论 1 277
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 63,867评论 5 368
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,695评论 1 282
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 38,064评论 3 399
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,705评论 0 258
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 42,915评论 1 300
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,677评论 2 323
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,796评论 1 333
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,432评论 4 322
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 39,041评论 3 307
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,992评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,223评论 1 260
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 45,185评论 2 352
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,535评论 2 343