前端規範之JS代碼規範（ESLint + Prettier）

• 2021 年 9 月 27 日
• 筆記

    代碼規範是軟件開發領域經久不衰的話題，幾乎所有工程師在開發過程中都會遇到或思考過這一問題。而隨着前端應用的大型化和複雜化，越來越多的前端團隊也開始重視代碼規範。同樣，前段時間，筆者所在的團隊也開展了一波開源治理，而其中代碼規範就佔據了很重要的一項。接下來的幾篇文章，將會對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:recommended或eslint: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配置。

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',
};

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

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