中小型前端團隊代碼規範工程化最佳實踐 - ESLint

作者：axuebing

來源：Segmentfault 思否社區

前言

There are a thousand Hamlets in a thousand people's eyes.

一千個程序員，就有一千種代碼風格。在前端開發中，有幾個至今還在爭論的代碼風格差異：

• 單引號還是雙引號？

• 代碼行結束是否需要分號？

• 兩個空格還是四個空格？

• ...

這幾個代碼風格差異在協同開發中經常會被互相吐槽，甚至不能忍受。

除此之外，由於 JavaScript 的靈活性，往往一段代碼能有多種寫法，這時候也會導致協同時差異。並且，有一些寫法可能會導致不易發現的 bug，或者這些寫法的性能不好，開發時也應該避免。

爲了解決這類靜態代碼問題，每個團隊都需要一個統一的 JavaScript 代碼規範，團隊成員都遵守這份代碼規範來編寫代碼。當然，靠人來保障代碼規範是不可靠的，需要有對應的工具來保障，ESLint 就是這個工具。

有的讀者看到這裏，可能會說：Prettier 也可以保證代碼風格一致。是的，Prettier 確實可以按照設置的規則對代碼進行統一格式化，後面的文章也會有對應的介紹。但是需要明確的一點是，Prettier 只會在格式上對代碼進行格式化，一些隱藏的代碼質量問題 Prettier 是無法發現的，而 ESLint 可以。

關於 ESLint

關於 ESLint，它的 Slogan 是 Find and fix problems in your JavaScript code。如上文所說，它可以發現並修復你 JavaScript 代碼中的問題。來看一下官網上描述 ESLint 具備的三個特性：

• Find Problems。ESLint 通過靜態代碼分析可以快速發現代碼中的問題。ESLint 可以運行在大多數文本編輯器中，並且也可以在工作流中接入 ESLint

• Fix Automatically。ESLint 發現的很多問題都可以自動修復

• Customize。可以定製 ESLint 檢查規則

基於以上描述，我們在前端工程化中可以這樣使用 ESLint：

1. 基於業界現有的 ESLint 規範和團隊代碼習慣定製一套統一的 ESLint 代碼規則

2. 將統一代碼規則封裝成 ESLint 規則包接入

3. 將 ESLint 接入腳手架、編輯器以及研發工作流中

快速上手

先簡單介紹一下如何使用 ESLint，如果已經有所瞭解的同學，可以直接跳過這一節。

新建一個包含 package.json 的目錄（可以在空目錄下執行 npm init -y），新建一個 index.js：

// index.js
const name = 'axuebin'

安裝 eslint ：

npm install eslint --save-dev

然後執行 ./node_modules/.bin/eslint --init 或者 npx eslint --init 生成一個 ESLint 配置文件 .eslintc.js：

module.exports = {
  env: {
    es2021: true,
  },
  extends: 'eslint:recommended',
  parserOptions: {
    ecmaVersion: 12,
  },
  rules: {},
};

生成好配置文件之後，就可以執行 ./node_modules/.bin/eslint index.js 或者 npx eslint index.js 命令對文件進行檢查。結果如下

index.js 中的代碼命中了 no-unused-vars 這個規則，默認情況下，這個規則是會報 error 的，也就是 ESLint 不允許代碼中出現未被使用的變量。這是一個好習慣，有利於代碼的維護。

簡單配置

我們來嘗試配置 ESLint 的檢查規則。以分號和引號舉例，現在你作爲團隊代碼規範的指定人，希望團隊成員開發的代碼，都是單引號和帶分號的。

打開 .eslintrc.js 配置文件，在 rules 中添加相關配置項：

module.exports = {
  env: {
    es2021: true,
  },
  extends: 'eslint:recommended',
  parserOptions: {
    ecmaVersion: 12,
  },
  rules: {
    semi: ['error', 'always'],
    quotes: ['error', 'single'],
  },
};

然後我們將 index.js 中的代碼改成：

// index.js
const name = "axuebin"

執行 eslint 命令之後：

可以看到檢查結果如下：

• [no-unused-vars] 'name' is assigned a value but never used。定義了 name 變量卻未使用。

• [quotes] Strings must use singlequote。字符串必須使用單引號。

• [semi] Missing semicolon。缺失分號。

老老實實地按照規範修改代碼，使用單引號並將加上分號。當然，如果你們希望是雙引號和不帶分號，修改相應的配置即可。

具體各個規則如何配置可以查看：

https://eslint.org/docs/rules

自動修復

執行 eslint xxx --fix 可以自動修復一些代碼中的問題，將無法自動修復的問題暴露出來。比如上文中提到的引號和分號的問題，就可以通過 --fix 自動修復，而 no-unused-vars 變量未使用的問題，ESLint 就無法自動修復。

使用配置包

在 init 生成的配置文件中，我們看到包含這一行代碼：

module.exports = {
  extends: "eslint:recommended"
}

這一行代碼的意思是，使用 ESLint 的推薦配置。 extends: 'xxx' 就是 繼承，當前的配置繼承於 xxx 的配置，在此基礎上進行擴展。

因此，我們也可以使用任意封裝好的配置，可以在 NPM 上或者 GItHub 上搜索 eslint-config 關鍵詞獲取，本文我們將這類封裝好的配置稱作 “配置集”。比較常見的配置包有以下幾個：

• eslint-config-airbnb: Airbnb 公司提供的配置集

• eslint-config-prettier: 使用這個配置集，會關閉一些可能與 Prettier 衝突的規則

• eslint-config-react: create react app 使用的配置集

• eslint-config-vue: vuejs 使用的配置集

• ...

最佳實踐

簡單瞭解完 ESLint 之後，對於 ESLint 的更多使用細節以及原理，在本篇文章就不展開了，感興趣的朋友可以在官網詳細瞭解。本文重點還是在於如何在團隊工程化體系中落地 ESLint，這裏提幾個最佳實踐。

抽象配置集

對於獨立開發者以及業務場景比較簡單的小型團隊而言，使用現成、完備的第三方配置集是非常高效的，可以較低成本低接入 ESLint 代碼檢查。

但是，對於中大型團隊而言，在實際代碼規範落地的過程中我們會發現，不可能存在一個能夠完全符合團隊風格的三方配置包，我們還是會在 extends 三方配置集的基礎上，再手動在 rules 配置里加一些自定義的規則。時間長了，有可能 A 應用和 B 應用裏的 rules 就不一樣了，就很難達到統一的目的。

這時候，就需要一箇中心化的方式來管理配置包：根據團隊代碼風格整理（或者基於現有的三方配置集）發佈一個配置集，團隊統一使用這個包，就可以做到中心化管理和更新。

除此之外，從技術層面考慮，目前一個前端團隊的面對的場景可能比較複雜。比如：

• 技術選型不一致：框架上 PC 使用 React，H5 使用 Vue；是否使用 TypeScript

• 跨端場景多：Web 端和小程序端，還有 Node

• ...

以上問題在真實開發中都是存在的，所以在代碼規範的工程化方案落地時，一個單一功能的配置集是不夠用的，這時候還需要考慮這個配置集如何抽象。

爲了解決以上問題，這裏提供一種解決方案的思路：

具體拆解來看，就是有一個類似 eslint-config-standard 的基礎規則集（包括代碼風格、變量相關、ES6 語法等），在此基礎之上集成社區的一些插件（Vue/React）等，封裝成統一的一個 NPM Package 發佈，消費時根據當前應用類型通過不同路徑來 extends 對應的配置集。

這裏有一個 Demo，感興趣的朋友可以看一下：eslint-config-axuebin

開發插件

ESLint 提供了豐富的配置供開發者選擇，但是在複雜的業務場景和特定的技術棧下，這些通用規則是不夠用的。ESLint 通過插件的形式賦予了擴展性，開發者可以自定義任意的檢查規則，比如 eslint-plugin-vue / eslint-plugin-react 就是 Vue / React 框架中使用的擴展插件，官網也提供了相關文檔引導開發者開發一個插件。

一般來說，我們也不需要開發插件，但我們至少需要了解有這麼個東西。在做一些團隊代碼質量檢查的時候，我們可能會有一些特殊的業務邏輯，這時候 ESLint 插件是可以幫助我們做一些事情。

這裏就不展開了，主要就是一些 AST 的用法，照着官方文檔就可以上手，或者可以參考現有的一些插件寫法。

腳手架 / CLI 工具

當有了團隊的統一 ESLint 配置集和插件之後，我們會將它們集成到腳手架中，方便新項目集成和開箱即用。但是對於一些老項目，如果需要手動改造還是會有一些麻煩的，這時候就可以藉助於 CLI 來完成一鍵升級。

本文結合上文的 Demo eslint-config-axuebin，設計一個簡單的 CLI Demo。由於當前配置也比較簡單，所以 CLI 只需要做幾件簡單的事情即可：

• 詢問用戶當前項目的類型（是 JavaScript 還是 TypeScript、是 React 還是 Vue）

• 根據項目類型寫 .eslintrc.js 文件

• 根據項目類型安裝所需依賴（比如 vue 需要 eslint-plugin-vue）

• 在 package.json 的 scripts 中寫入 "lint": "eslint src test --fix"

核心代碼如下：

const path = require('path');
const fs = require('fs');
const chalk = require('chalk');
const spawn = require('cross-spawn');

const { askForLanguage, askForFrame } = require('./ask');
const { eslintrcConfig, needDeps } = require('./config');

module.exports = async () => {
  const language = await askForLanguage();
  const frame = await askForFrame();

  let type = language;
  if (frame) {
    type += `/${frame}`;
  }

  fs.writeFileSync(
    path.join(process.cwd(), '.eslintrc.js'),
    `// Documentation\n// https://github.com/axuebin/eslint-config-axuebin\nmodule.exports = ${JSON.stringify(
      eslintrcConfig(type),
      null,
      2
    )}`
  );

  const deps = needDeps.javascript;
  if (language === 'typescript') {
    deps.concat(needDeps.typescript);
  }
  if (frame) {
    deps.concat(needDeps[frame]);
  }

  spawn.sync('npm', ['install', ...deps, '--save'], { stdio: 'inherit' });
};

可運行的 CLI Demo 代碼見：axb-lint，在項目目錄下執行：axblint eslint 即可，如圖：

自動化

配置了 ESLint 之後，我們需要讓開發者感知到 ESLint 的約束。開發者可以自己運行 eslint 命令來跑代碼檢查，這不夠高效，所以我們需要一些自動化手段來做這個事情。當然 在開發時，編輯器也有提供相應的功能可以根據當前工作區下的 ESLint 配置文件來檢查當前正在編輯的文件，這個不是我們關心的重點。

一般我們會在有以下幾種方式做 ESLint 檢查：

• 開發時：依賴編輯器的能力

• 手動運行：在終端中手動執行 eslint 命令

• pre-commit：在提交 git 前自動執行 eslint 命令

• ci：依賴 git 的持續集成，可以將檢查結果輸出文件上傳到服務器

這裏提一下 pre-commit 的方案，在每一次本地開發完成提交代碼前就做 ESLint 檢查，保證雲端的代碼是統一規範的。

這種方式非常簡單，只需要在項目中依賴 husky 和 lint-staged 即可完成。安裝好依賴之後，在 package.json 文件加入以下配置即可：

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": "eslint --cache --fix"
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  }
}

效果如圖所示：

如果代碼跑 ESLint 檢查拋了 Error 錯誤，則會中斷 commit 流程：

這樣就可以確保提交到 GitHub 倉庫上的代碼是統一規範的。（當然，如果認爲將這些配置文件都刪了，那也是沒辦法的）

總結

本文介紹了 ESLint 在中小型前端團隊的一些最佳實踐的想法，大家可以在此基礎上擴展，制訂一套完善的 ESLint 工作流，落地到自己團隊中。

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/zlsWaZjHfiQ14XPms2yHtw