程式碼規範是軟體開發領域經久不衰的話題,幾乎所有工程師在開發過程中都會遇到或思考過這一問題。而隨著前端應用的大型化和複雜化,越來越多的前端團隊也開始重視程式碼規範。同樣,前段時間,筆者所在的團隊也開展了一波開源治理,而其中程式碼規範就佔據了很重要的一項。接下來的幾篇文章,將會對JS程式碼規範、CSS規範、Git工作流規範以及文件規範進行詳細的介紹~

系列文章:

  • 前端規範之JS程式碼規範(ESLint + Prettier)
  • 前端規範之CSS規範(Stylelint)
  • 前端規範之Gti工作流規範(Husky + Commitlint + Lint-staged)
  • 前端規範之文件規範

本文主要介紹了前端規範之JS程式碼規範(ESLint + Prettier),將會對ESLint和Prettier的使用進行介紹,歡迎大家交流討論~

1. 統一程式碼風格的重要性

1.1 為什麼要統一程式碼風格

團隊千千萬,團隊中每個人的程式碼風格也是千千萬。比如有的同學寫程式碼就喜歡用雙引號,縮排用兩個字元,而其他同學卻可能更喜歡用單引號,四個字元縮排。而團隊中的人一多,一往程式碼倉庫提交程式碼,難免會出現下面這些情況:

  (1)如果沒有統一程式碼風格,diff時可能會出現很多因為格式不同的問題,不便於我們檢視提交程式碼所做的修改

如下圖所示,提交的檔案內容其實沒有變化,只是程式碼風格變了(雙引號變成了單引號,縮排從兩個字元變成了四個字元),但是diff時大段程式碼會標紅,不利於我們檢視提交的修改。

 (2)每個團隊都有自己的標準,新人加入需要花較長時間才能熟悉團隊所使用的程式碼風格,不利於效率的提

1.2 如何統一程式碼風格

為了統一程式碼風格,並且克服每個團隊自己制定標準所帶來的不足,一種簡單方便的方法就是採用業界提供的標準和工具,也就是我們經常所說的Lint檢查工具。前端中常用的Lint檢查工具包括了JSLint、ESLint和Stylelint等,這些工具能夠提供程式碼質量和程式碼風格檢查的功能,並且可以根據個人/團隊的程式碼風格進行對配置檔案進行配置,有效的提高了我們程式碼開發的效率和質量

下面主要列舉了我們團隊現在主要採用的一些Lint檢查工具,以及相關的VSCode輔助外掛,幫助我們完成JS程式碼規範、CSS程式碼規範和Git工作流規範的檢查。

2. ESLint

2.1 什麼是ESLint

ESLint 是一款外掛化的JavaScript程式碼靜態檢查工具,其核心是通過對程式碼解析得到的 AST(Abstract Syntax Tree,抽象語法樹)進行模式匹配,來分析程式碼達到檢查程式碼質量和風格問題的能力。

ESLint 的使用其實並不複雜。安裝相關依賴之後,可以直接使用開源的配置方案,例如eslint-config-airbnb或eslint-config-standard,當然,你也可以根據個人或團隊的程式碼風格進行配置。配置完成之後,就可以通過命令列工具或藉助編輯器整合的 ESLint 功能對工程程式碼進行靜態檢查,發現和修復不符合規範的程式碼,ESLint提供的auto-fix能力也能夠幫助我們自動修復一些程式碼格式問題。

2.2 安裝ESLint

 (1)腳手架自動安裝

如果是採用腳手架如Vue-Cli建立專案,在建立專案時就可以選擇安裝ESLint,安裝完成後,會自動在專案根目錄生成一個.eslintrc.js檔案,裡面已經生成了ESLint的初始化預設配置。

 (2)手動安裝

如果是已經存在一個專案,並且想要安裝ESLint,可以通過npm的方式進行安裝。

npm install eslint --save-dev

安裝完成後,可以執行下面命令進行ESLint的初始化配置。

eslint --init

經過一系列一問一答的環節後,你會發現在你專案根目錄已經生成了一個 .eslintrc.js檔案,該檔案主要用來進行ESLint的配置。

2.3 ESLint配置方式

ESlint 被設計為完全可配置的,我們可以混合和匹配 ESLint 預設繫結的規則和自己定義的規則,根據實際需求對每一個規則進行開啟或關閉,以讓 ESLint 更適合我們的專案。一般有兩種主要的方式來配置 ESLint:

  (1)Configuration Comments - 使用註釋把lint規則嵌入到原始碼中

    這種配置方式允許我們使用JavaScript註釋把配置資訊直接嵌入到一個程式碼原始檔中,如下面的程式碼所示,可以直接在程式碼中使用ESLint能夠識別的註釋方式,進行Lint規則的定義,下面的規則表示如果使用console語法便會報錯。

/* eslint no-console: "error" */
console.log('this is an eslint rule check!');

當我們用命令列執行eslint xxx.js檢查上述檔案時,就會發現eslint給出報錯資訊。

  (2)Configuration Files - 使用配置檔案進行lint規則配置

除了上面的配置方式,另外一個更好的方式就是在專案根目錄建立配置檔案進行ESLint的配置,目前配置檔案主要支援以下三種檔案型別:

  • JavaScript(eslintrc.js)
  • YAML(eslintrc.yaml)
  • JSON(eslintrc.json)

另外,我們也可以在package.json檔案中新增 eslintConfig欄位進行配置。

在我們團隊平時的開發中,一般採用了在根目錄建立.eslintrc.js的方式對eslint進行配置。如下圖所示,給出了使用Vue-Cli建立專案後.eslintrc.js中的預設配置。

module.exports = {
  root: true,
  env: {
    node: true,
  },
  extends: ["plugin:vue/essential", "eslint:recommended", "@vue/prettier"],
  parserOptions: {
    parser: "babel-eslint",
  },
  rules: {
    "no-console": process.env.NODE_ENV === "production" ? "warn" : "off",
    "no-debugger": process.env.NODE_ENV === "production" ? "warn" : "off",
  },
};

2.4 ESLint配置項解析

接下來主要對ESLint配置檔案中的配置項進行介紹。

  (1)parser解析器

ESLint 預設使用Espreer作為其解析器,但是該解析器僅支援最新的ECMPScript(es5)標準,對於實驗性的語法和非標準(例如 Flow或TypeScript型別)語法是不支援的。因此,開源社群提供了以下兩種解析器來豐富相關的功能:

babel-eslint:Babel一個工具鏈,主要用於將ECMAScript 2015+(es6+) 版本的程式碼轉換為向後相容的JavaScript語法,以便能夠執行在當前和舊版本的瀏覽器或其他環境中。因此,如果在專案中使用es6,就需要將解析器改成babel-eslint。

@typescript-eslint/parser:該解析器將TypeScript轉換成與estree相容的形式, 允許ESLint驗證TypeScript原始碼。

  (2)parserOptions解析器選項

除了可以自定義解析器外,ESLint允許指定你想要支援的JavaScript語言選項。預設情況下,ESLint支援ECMPScript 5語法。你可以覆蓋該設定,以啟用對ECMPScript其它版本和JSX的支援。

  (3)env和global - 環境和全域性變數

ESLint 會檢測未宣告的變數,併發出警告,但是有些變數是我們引入的庫宣告的,這裡就需要提前在配置中宣告。每個變數有三個選項,writable,readonly和off,分別表示可重寫,不可重寫和禁用。

{
"globals": {
// 宣告 jQuery 物件為全域性變數
"$": false, // true表示該變數為 writeable,而 false 表示 readonly
"jQuery": false
}
}

在globals中一個個的進行宣告未免有點繁瑣,這個時候就需要使用到env,這是對一個環境定義的一組全域性變數的預設。當然,我們可以在golbals中使用字串off禁用全域性變數來覆蓋env中的宣告。

{
"env": {
"browser": true,
"es2021": true,
"jquery": true // 環境中開啟jquery,表示聲明瞭jquery相關的全域性變數,無需在globals二次宣告
}
}

如果是微信小程式開發,env並沒有定義微信小程式變數,需要在globals中手動宣告全域性變數,否則在檔案中引入變數,會提示報錯。宣告如下所示:

{
globals: {
wx: true,
App: true,
Page: true,
Component: true,
getApp: true,
getCurrentPages: true,
Behavior: true,
global: true,
__wxConfig: true,
},
}

  (4)rules規則

ESLint 附帶有大量的規則,你可以在配置檔案的rules屬性中配置你想要的規則。要改變一個規則設定,你必須將規則 ID 設定為下列值之一:

  • off或 0:關閉規則
  • warn或 1:開啟規則,warn級別的錯誤 (不會導致程式退出)
  • error或 2:開啟規則,error級別的錯誤(當被觸發的時候,程式會退出)

如以下程式碼,在rules中設定關閉某些規則

rules: {'no-loop-func': 'off',
'no-param-reassign': 'off',
'no-nested-ternary': 'off',
no-underscore-dangle': 'off',
},

  (5)plugins外掛

雖然官方提供了上百種的規則可供選擇,但是這還不夠,因為官方的規則只能檢查標準的JavaScript語法,如果你寫的是JSX或者TypeScript,ESLint 的規則就開始束手無策了。

這個時候就需要安裝 ESLint 的外掛,來定製一些特定的規則進行檢查。ESLint 的外掛與擴充套件一樣有固定的命名格式,以eslint-plugin-開頭,使用的時候也可以省略這個頭。

舉個例子,我們要在專案中使用TypeScript,前面提到過,需要將解析器改為@typescript-eslint/parser,同時需要安裝@typescript-eslint/eslint-plugin外掛來拓展規則,新增的plugins中的規則預設是不開啟的,我們需要在rules中選擇我們要使用的規則。也就是說 plugins是要和rules結合使用的。如下所示:

// npm i --save-dev @typescript-eslint/eslint-plugin    // 註冊外掛
{
"parser": "@typescript-eslint/parser",
"plugins": ["@typescript-eslint"], // 引入外掛
"rules": {
"@typescript-eslint/rule-name": "error" // 使用外掛規則
'@typescript-eslint/adjacent-overload-signatures': 'error',
'@typescript-eslint/ban-ts-comment': 'error',
'@typescript-eslint/ban-types': 'error',
'@typescript-eslint/explicit-module-boundary-types': 'warn',
'@typescript-eslint/no-array-constructor': 'error',
'no-empty-function': 'off',
'@typescript-eslint/no-empty-function': 'error',
'@typescript-eslint/no-empty-interface': 'error',
'@typescript-eslint/no-explicit-any': 'warn',
'@typescript-eslint/no-extra-non-null-assertion': 'error',
...
}
}

  (6)extends擴充套件

extends可以理解為一份配置好的plugin和rules,extends屬性值一般包括以下兩種:

  • 指定配置的字串: 比如官方提供的兩個拓展eslint:recommendedeslint:all,可以啟用當前安裝的 ESLint 中所有的核心規則,省得我們在rules中一一配置。
  • 字串陣列:每個配置繼承它前面的配置。如下所示,拓展是一個數組,ESLint 遞迴地擴充套件配置, 然後使用rules屬性來拓展或者覆蓋extends配置規則。
{
"extends": [
"eslint:recommended", // 官方拓展
"plugin:@typescript-eslint/recommended", // 外掛拓展
"standard", // npm包,開源社群流行的配置方案,比如:eslint-config-airbnb、eslint-config-standard
],
"rules": {
"indent": ["error", 4], // 拓展或覆蓋extends配置的規則
"no-console": "off",
}
};

2.5 執行ESLint檢查檔案

當我們配置好.eslintrc.js檔案後,我們就可以通過執行ESLint相關命令,對指定檔案進行檢查,假設當前的專案目錄如下所示:

其中,.eslintrc.js檔案的配置如下,這裡採用了Vue-Cli建立專案後給出的預設配置。

module.exports = {
  root: true,
  env: {
    node: true,
  },
  extends: ["plugin:vue/essential", "eslint:recommended", "@vue/prettier"],
  parserOptions: {
    parser: "babel-eslint",
  },
  rules: {
    "no-console": process.env.NODE_ENV === "production" ? "warn" : "off",
    "no-debugger": process.env.NODE_ENV === "production" ? "warn" : "off",
  },
};

當我們想對某個檔案進行檢查時,只需要在當前目錄開啟命令列視窗,輸入以下命令,就可以對某個檔案或某個目錄下的所有檔案進行檢查。如果執行完命令後什麼也沒有輸出,就說明我們的程式碼已經通過ESLint檢查,可以放心提交程式碼。

eslint src/APP.vue  // 檢查指定的檔案
eslint src/*.vue   // 檢查src目錄下的所有檔案

但是如果出現以下提示或報錯,就說明我們的程式碼沒有通過ESLint的檢查,需要按照提示進行修改。

有些同學一執行完上述命令,可能會嚇了一跳,怎麼報了這麼多錯誤?不急,我們可以執行以下的ESLint自動修復命令,對一些錯誤進行自動修復。不過,這個命令只能自動修復一些程式碼格式上的錯誤(比如ESLint的配置要求需要使用雙引號,但是寫程式碼時採用了單引號而報錯),對於一些語法錯誤,就需要我們手動去修復。

eslint src/APP.vue --fix   // 檢查指定的檔案,並且自動修復錯誤
eslint src/*.vue --fix // 檢查src目錄下的所有檔案,並且自動修復錯誤

2.6 跳過ESLint的檢查

在實際的使用場景中,我們可能存在某些檔案或某行程式碼,希望能夠跳過ESLint的檢查,下面主要介紹了幾種跳過ESLint檢查的方式:

    (1)使用註釋跳過ESLint的檢查

  • 塊註釋: 使用如下方式,可以在整個檔案或者程式碼塊禁用所有規則或者禁用特定規則:
/* eslint-disable */
alert('該註釋放在檔案頂部,整個檔案都不會出現 lint 警告'); /* eslint-disable */
alert('塊註釋 - 禁用所有規則');
/* eslint-enable */ /* eslint-disable no-console, no-alert */
alert('塊註釋 - 禁用 no-console, no-alert 特定規則');
/* eslint-enable no-console, no-alert */
  • 行註釋: 使用如下方式可以在某一特定的行上禁用所有規則或者禁用特定規則:
alert('禁用該行所有規則'); // eslint-disable-line

// eslint-disable-next-line
alert('禁用該行所有規則'); /* eslint-disable-next-line no-alert */
alert('禁用該行 no-alert 特定規則'); alert(
'禁用該行 no-alert, quotes, semi 特定規則'
); /* eslint-disable-line no-alert, quotes, semi*/

2)建立.eslintignore檔案忽略某些檔案的檢查

在專案根目錄建立.eslintignore檔案,在該檔案中新增需要跳過檢查的檔名稱,ESLint將會跳過這些檔案的檢查。如下所示,ESLint將會跳過dist、node_modules和package.json檔案的檢查。

dist
node_modules
package.json

3. Prettier

3.1 什麼是Prettier

Prettier是一個程式碼格式化工具,可以格式化程式碼,但不具備程式碼檢查功能,它可以通過解析程式碼並使用自己的規則重新列印它,並考慮最大行長來強制一致的樣式,並在必要時包裝程式碼,如今,它已成為解決所有程式碼格式問題的優選方案,支援多種語言,可以將ESLint和Prettier結合使用,提高程式碼質量。

3.2 為什麼要用Prettier

上面Prettier的定義一看,是不是覺得和ESLint差不了多少?那麼,有了ESLint,為什麼還要用Prettier呢?

其實呀,ESLint雖然是一個程式碼檢測工具,可以檢測程式碼質量問題並給出提示,但是提供的格式化功能有限,在程式碼風格上面做的不是很好,並且也只能格式化JS,不支援CSS,HTML等語言。而在程式碼風格上面,Prettier具有更加強大的功能,並且能夠支援包括 JavaScript、TypeScript、各種 CSS、Vue 和 Markdown 等前端絕大部分的語言和檔案格式。因此,我們一般會將ESLint和Prettier一起結合起來使用,用ESLint進行程式碼校驗,用Prettier統一程式碼風格。

3.3 安裝Prettier

 (1)腳手架自動安裝

如果是採用腳手架如Vue-Cli建立專案,在建立專案時就可以選擇安裝Prettier,安裝完成後,會自動在專案根目錄生成一個.eslintrc.js檔案,裡面的預設配置中已經包含了prettier的相關擴充套件。

 (2)手動安裝

如果已經存在一個專案,並且想要安裝Prettier,可以通過npm的方式進行安裝。

npm install prettier --save-dev

3.4 安裝eslint-config-prettier

安裝好Prettier之後,我們還需要安裝eslint-config-prettier,這是因為eslint和prettier裡面的一些規則可能會存在衝突,這個時候我們就需要安裝eslint-config-prettier,並且關掉所有和prettier衝突的eslint配置。

通過npm安裝eslint-config-prettier。

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

安裝好eslint-config-prettier之後,接下來我們就需要關掉所有和prettier衝突的eslint配置。這裡只需要在.eslintrc.js的extends中將prettier設定為最後一個extends即可,相當於用 prettier 的規則,覆蓋掉 eslint:recommended 的部分規則。

extends: ["eslint:recommended", "prettier"],

3.5 安裝eslint-plugin-prettier

接下來,我們還需要安裝eslint-plugin-prettier,eslint-plugin-prettier的作用時是將prettier 的能力整合到eslint中,使得我們在執行eslint檢查我們的程式碼時,能夠按照prettier的規則檢查程式碼規範性,並進行修復。

使用npm安裝eslint-plugin-prettier。

npm install eslint-plugin-prettier

安裝eslint-plugin-prettier後,需要對.eslintrc.js進行配置。

{
"rules":{
"prettier/prettier":"error"
},
"plugins": ["prettier"],
}

除了上面這種配置之外,我們也可以直接將上面兩個步驟結合在一起,使用下面的配置就可以。

{
"extends": [
"eslint:recommended",
"plugin:prettier/recommended"
]
}

3.6 配置檔案

Prettier和ESLint一樣,支援我們通過配置檔案的方式,實現自定義配置,覆蓋原來的Prettier配置。

我們可以在根目錄建立.prettierrc檔案,.prettierrc檔案支援寫入YAML,JSON的配置格式,並且支援.yaml,.yml,.json和.js字尾。在平時的開發中,我們團隊一般會選擇建立.prettierrc.js檔案,實現對prettier配置的覆蓋。

在.prettierrc.js檔案中,我們可以對prettier的預設配置進行修改。

module.exports = {
// 一行最多 120 字元
printWidth: 120,
// 使用 2 個空格縮排
tabWidth: 2,
// 不使用縮排符,而使用空格
useTabs: false,
// 行尾需要有分號
semi: true,
// 使用單引號
singleQuote: true,
// 物件的 key 僅在必要時用引號
quoteProps: 'as-needed',
// jsx 不使用單引號,而使用雙引號
jsxSingleQuote: false,
// 末尾需要有逗號
trailingComma: 'all',
// 大括號內的首尾需要空格
bracketSpacing: true,
// jsx 標籤的反尖括號需要換行
jsxBracketSameLine: false,
// 箭頭函式,只有一個引數的時候,也需要括號
arrowParens: 'always',
// 每個檔案格式化的範圍是檔案的全部內容
rangeStart: 0,
rangeEnd: null,
// 不需要寫檔案開頭的 @prettier
requirePragma: false,
// 不需要自動在檔案開頭插入 @prettier
insertPragma: false,
// 使用預設的折行標準
proseWrap: 'preserve',
// 根據顯示樣式決定 html 要不要折行
htmlWhitespaceSensitivity: 'css',
// vue 檔案中的 script 和 style 內不用縮排
vueIndentScriptAndStyle: false,
// 換行符使用 lf
endOfLine: 'lf',
// 格式化內嵌程式碼
embeddedLanguageFormatting: 'auto',
};

3.7 忽略某些檔案的格式化

Prettier和ESLint一樣,也支援忽略對某些檔案的格式化。如果我們存在一些不需要格式化的檔案,可以在根目錄建立.prettierignore檔案,並且將不需要格式化的檔案或目錄名稱寫在該檔案中。

dist
node_modules
.eslintignore
.prettierignore

4. VSCode外掛

4.1 安裝VSCode外掛

配置好ESLint和Prettier之後,我們通過執行eslint命令,就可以對我們程式碼進行檢查啦。但是,每次要手動執行命令才能檢查我們的程式碼還是有點麻煩,有沒有更簡單的方式,讓我們在編寫程式碼的過程中,就能夠對我們的程式碼進行檢查,並且自動修復一些錯誤呢?接下來,接下來,VSCode外掛就登場啦~

首先,我們需要安裝的ESLint外掛,安裝方法很簡單,在VSCode的EXTENSIONS中找到ESLint外掛,然後點選install就可以啦。

接著,我們還需要安裝Prettier外掛。

最後,我們也把EditorConfig for VS Code外掛安裝上,這個外掛可以讓編譯器讀取配置檔案,並且按照配置檔案裡面的規定來格式化程式碼,有了這個外掛,只要定義好一份配置檔案,就算團隊成員用的編譯器不同,也能夠輸出風格統一的程式碼。

4.2 配置setting.json檔案

安裝好外掛之後,我們還需要設定VSCode的setting.json檔案,實現儲存程式碼時就自動執行ESLint檢查。VSCode的setting.json設定分為工作區和使用者兩個級別,其中使用者區會對所有專案生效,而工作區的設定只會對當前專案生效。

  (1)使用者區setting.json配置

點選VSCode左下角的設定按鈕,選擇Settings,選擇以文字編輯形式開啟setting.json,並且在setting.json中加入以下程式碼。配置完成之後,當我們儲存某個檔案時,就可以自動對當前檔案進行ESLint檢查,並且自動對一些錯誤進行修復啦。

{
// #每次儲存的時候自動格式化
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
},

  (2)工作區setting.json配置

除了配置使用者區的setting.json之外,我們也可以配置工作區的setting.json,工作區的配置只會對當前專案生效。

首先,我們需要在專案根目錄建立.vscode目錄,並且在該目錄下建立setting.json檔案。

接著,在setting.json中加入以下程式碼,配置完成後,當我們儲存該專案中某個檔案時,也會自動對該檔案進行ESLint檢查,並且自動修復一些問題。

{
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true,
},
"eslint.validate": ["typescript", "javascript", "vue"]
}

4.3 配置EditorConfig檔案

上面在安裝VSCode外掛時,我們提到了要安裝EditorConfig for VS Code外掛,那這個外掛需要怎麼起作用呢?

首先,我們需要在專案根目錄建立.editorconfig檔案。建立完成之後,這個檔案裡面定義的程式碼規範規則會高於編譯器預設的程式碼規範規則。

接著,我們只需要在.editorconfig檔案中加入我們想要覆蓋的編譯器的配置,比如下面的配置定義了縮排為2個空格,那麼就算編譯器預設的是4個空格的縮排,最後也會按照我們的.editorconfig配置,按照2個空格進行縮排。

root = true

[*]
charset = utf-8
indent_style = space
indent_size = 2
insert_final_newline = true
trim_trailing_whitespace = true
end_of_line = auto

當我們完成上面的步驟之後,接下來我們只要編寫程式碼,儲存,就能夠得到一份風格統一的程式碼啦~