前言

ESLint 在項目中已經是大家見慣不慣的存在，你可能很厭煩動不動跳出來的 ESLint 報錯，也可能很享受經過統一校驗的工工整整的代碼，無論如何，我的意見是，在稍微正式點的項目中都要有 ESLint 的存在，無論是直接使用簡單的 recommend 配置如 extends: ['eslint: recommend']，還是精心研究了一整套適用于自己的規則集，Lint 工具的最大幫助就是保持語法統一，至少項目中的所有 JavaScript 文件應使用統一的單雙引號、分號、縮進等風格(僅靠編輯器并不能保證)。

其次，Lint 幫助你的代碼更加簡潔、有效，如不允許未使用的變量、JSX/TSX 中使用簡寫的 true 屬性( 而不是 )等、還有一點值得一提，ESLint 并不會一直嘗試去簡化你的代碼，在很多情況下它會要求你寫更多代碼來換取可讀性和安全性的提升，尤其是在 TypeScript 場景下，explicit-module-boundary-types 規則會要求你為函數與類方法顯式的聲明其返回值，switch-exhaustiveness-check 規則會要求你處理聯合類型變量的所有類型分支。

本文來自于我在所在團隊(淘寶店鋪)內部制定、落地、推廣 ESLint 規則集的收獲，將會簡要的介紹一批我認為在 TypeScript 分享中非常有必要的規則，通過這篇文章，你會了解到在制定規則時我們考慮的是什么，對于 TypeScript 代碼進行約束的思考，以及如何在自己的團隊內推廣這一套規則。

另外，淘系技術部前端架構團隊正在淘系內推廣 AppLint，準備將 ESLint 推廣到整個淘系前端作為 CI/CD 的卡口之一，歡迎集團的同學了解并試用。

P.S. 我參與的 QCon+ 專題：TypeScript 在中大型項目中的落地實踐[1] 中，淘寶店鋪 TypeScript 研發規約落地[2] 這一課程包括了我們團隊從 JavaScript 遷移到 TypeScript 以及落地完整的研發規約經驗，歡迎來聽~

基礎約束

為了適應讀者可能有的不同的約束嚴格程度，這里將規則拆分為基礎約束與嚴格約束部分，基礎約束的規則以語法統一(包括實際代碼與類型部分)為主，推薦所有人在所有項目中使用，即使是個人項目——說實在的，都寫 TypeScript 了，還在意這小小的 Lint 規則?而嚴格約束部分更關注類型以及 ECMAScript、TypeScript 的特殊語法，適合對代碼質量要求較高的同學。這里不會給出推薦的錯誤等級，即使全部是 warn，只要你打開了，至少你也會在以后心情好的時候來修對吧?(對吧?)

array-type

TypeScript 中支持使用 Array 與 T[] 的形式聲明數組類型，此規則約束項目中對這兩種數組類型的聲明。

其支持的配置：

• 僅使用 Array 或 T[] 其中一種
• 對于原始類型與類型別名使用 T[]，對于對象類型、函數類型等使用 Array(推薦)

為什么?：對于這種效果完全一致的語法，我們需要的只是確定一個規范然后在所有地方使用這一規范。實際上，這一類規則(還有后面的類型斷言語法)就類似于單引號/雙引號，加不加分號這種基礎規則，如果你不能接受上一行代碼單引號這一行代碼雙引號，那么也沒理由能接受這里一個 Array 那里一個 number[]，另外，我個人推薦統一使用 []。

await-thenable

只允許對異步函數、Promise、PromiseLike 使用 await 調用

為什么：避免無意義的 await 調用。

ban-ts-comment

禁止 @ts- 指令的使用，或者允許其在提供了說明的情況下被使用，如：

// @ts-expect-error 這里的類型太復雜，日后補上 
// @ts-nocheck 未完成遷移的文件 

此規則推薦與 prefer-ts-expect-error 搭配使用，詳見下方。

為什么：如果說亂寫 any 叫 AnyScript，那么亂寫 @ts-ignore 就可以叫 IgnoreScript 了。

ban-types

禁止部分值被作為類型標注，此規則能夠對每一種被禁用的類型提供特定的說明來在觸發此規則報錯時給到良好的提示，場景如禁用 {}、Function、object 這一類被作為類型標注，

為什么?使用 {} 會讓你寸步難行：類型 {} 上不存在屬性 'foo'，所以用了 {} 你大概率在下面還需要類型斷言回去或者變 any，使用 object Function 毫無意義。

• 對于未知的對象類型，應使用 Record
• 對于函數類型，應使用入參、返回值被標注出來的具體類型：type SomeFunc = (arg1: string) => void ，或在未知的場景下使用 type SomeFunc = (...args: any[]) => any。

consistent-type-assertions

TypeScript 支持通過 as 與 <> 兩種不同的語法進行類型斷言，如：

const foo = {} as Foo; 
const foo = <Foo>{}; 
// 類似的還有常量斷言 
const foo = <const>[1, 2]; 
const foo = [1, 2, 3] as const; 

這一規則約束使用統一的類型斷言語法，我個人一般在 Tsx 中使用 as ，在其他時候盡可能的使用 <>，原因則是 <> 更加簡潔。

為什么：類似于 array-type，做語法統一，但需要注意的是在 Tsx 項目中使用 <> 斷言會導致報錯，因為不像泛型可以通過 來顯式告知編譯器這里是泛型語法而非組件。

explicit-module-boundary-types

函數與類方法的返回值需要被顯式的指定，而不是依賴類型推導，如：

const foo = (): Foo => {}; 

為什么：通過顯式指定來直觀的區分函數的功能，如副作用等，同時顯式指定的函數返回值也能在一定程度上提升 TypeScript Compiler 性能。

no-extra-non-null-assertion

不允許額外的重復非空斷言：

// x 
function foo(bar: number | undefined) { 
  const bar: number = bar!!!; 
} 

為什么：額，why not?

prefer-for-of

在你使用 for 循環遍歷數組時，如果索引僅僅用來訪問數組成員，則應該替換為 for...of。

為什么：如果不是為了兼容性場景，在這種場景下的確沒有必要使用 for 循環。

prefer-nullish-coalescing && prefer-optional-chain

使用 ?? 而不是 ||，使用 a?.b 而不是 a && a.b。

為什么：邏輯或 || 會將 0 與 "" 視為 false 而導致錯誤的應用默認值，而可選鏈相比于邏輯與 && 則能夠帶來更簡潔的語法(尤其是在屬性訪問嵌套多層，或值來自于一個函數時，如 document.querySelector)，以及與 ?? 更好的協作：const foo = a?.b?.c?.d ?? 'default';。

no-empty-interface

不允許定義空的接口，可配置為允許單繼承下的空接口：

// x 
interface Foo {} 
 
// √ 
interface Foo extends Bar {} 

為什么：沒有父類型的空接口實際上就等于 {}，雖然我不確定你使用它是為了什么，但我能告訴你這是不對的。而單繼承的空接口場景則是較多的，如先確定下繼承關系再在后續添加成員。

no-explicit-any

不允許顯式的 any。

實際上這條規則只被設置為 warn 等級，因為真的做到一個 any 不用或是全部替換成 unknown + 類型斷言 的形式成本都非常高。

推薦配合 tsconfig 的 --noImplicitAny (檢查隱式 any)來盡可能的保證類型的完整與覆蓋率。

no-inferrable-types

不允許不必要的類型標注，但可配置為允許類的屬性成員、函數的屬性成員進行額外標注。

const foo: string = "linbudu"; 
 
class Foo { 
  prop1: string = "linbudu"; 
} 
 
function foo(a: number = 5, b: boolean = true) { 
  // ... 
} 

為什么：對于普通變量來說，與實際賦值一致的類型標注確實是沒有意義的，TypeScript 的控制流分析能很好地做到這一點，而對于函數參數與類屬性，主要是為了確保一致性，即函數的所有參數(包括重載的各個聲明)、類的所有屬性都有類型標注，而不是僅為沒有初始值的參數/屬性進行標注。

no-non-null-asserted-nullish-coalescing

不允許非空斷言與空值合并同時使用：bar! ?? tmp

為什么：冗余

no-non-null-asserted-optional-chain

不允許非空斷言與可選鏈同時使用：foo?.bar!

為什么：和上一條規則一樣屬于冗余，同時意味著你對 ! ?? ?. 的理解存在著不當之處。

no-throw-literal

不允許直接 throw 一個字符串如：throw 'err'，只能拋出 Error 或基于 Error 派生類的實例，如：throw new Error('Oops!')。

為什么：拋出的 Error 實例能夠自動的收集調用棧信息，同時借助 proposal-error-cause[3] 提案還能夠跨越調用棧來附加錯誤原因傳遞上下文信息，不過，真的會有人直接拋出一個字符串嗎??

no-unnecessary-type-arguments

不允許與默認值一致的泛型參數，如：

function foo<T = number>() {} 
foo<number>(); 

為什么：出于代碼簡潔考慮。

no-unnecessary-type-assertion

不允許與實際值一致的類型斷言，如：const foo = 'foo' as string。

為什么：你懂的。

no-unnecessary-type-constraint

不允許與默認約束一致的泛型約束，如：interface FooAny {}。

為什么：同樣是出于簡化代碼的考慮，在 TS 3.9 版本以后，對于未指定的泛型約束，默認使用 unknown ，在這之前則是 any，知道這一點之后你就沒必要再多寫 extends unknown 了。

non-nullable-type-assertion-style

此規則要求在類型斷言僅起到去空值作用，如對于 string | undefined 類型斷言為 string時，將其替換為非空斷言 !

const foo: string | undefined = "foo"; 
 
// √ 
foo!; 
// x 
foo as string; 

為什么：當然是因為簡化代碼了!此規則的本質是檢查經過斷言后的類型子集是否僅剔除了空值部分，因此無需擔心對于多種有實際意義的類型分支的聯合類型誤判。

prefer-as-const

對于常量斷言，使用 as const 而不是 ，這一點類似于上面的 consistent-type-assertions 規則。

prefer-literal-enum-member

對于枚舉成員值，只允許使用普通字符串、數字、null、正則，而不允許變量復制、模板字符串等需要計算的操作。

為什么：雖然 TypeScript 是允許使用各種合法表達式作為枚舉成員的，但由于枚舉的編譯結果擁有自己的作用域，因此可能導致錯誤的賦值，如：

const imOutside = 2; 
const b = 2; 
enum Foo { 
  outer = imOutside, 
  a = 1, 
  b = a, 
  c = b, 
} 

這里 c == Foo.b == Foo.c == 1，還是 c == b == 2 ? 觀察下編譯結果：

"use strict"; 
const imOutside = 2; 
const b = 2; 
var Foo; 
(function (Foo) { 
  Foo[(Foo["outer"] = imOutside)] = "outer"; 
  Foo[(Foo["a"] = 1)] = "a"; 
  Foo[(Foo["b"] = 1)] = "b"; 
  Foo[(Foo["c"] = 1)] = "c"; 
})(Foo || (Foo = {})); 

懂伐小老弟?

prefer-ts-expect-error

使用 @ts-expect-error 而不是 @ts-ignore。

為什么：@ts-ignore 與 @ts-expect-error 二者的區別主要在于，前者是 ignore，是直接放棄了下一行的類型檢查而無論下一行是否真的有錯誤，后者則是期望下一行確實存在一個錯誤，并且會在下一行實際不存在錯誤時拋出一個錯誤。

這一類干涉代碼檢查指令的使用本就應該慎之又慎，在任何情況下都不應該被作為逃生艙門(因為它真的比 any 還好用)，如果你一定要用，也要確保用的恰當。

promise-function-async

返回 Promise 的函數必須被標記為 async，此規則能夠確保函數的調用方只需要處理 try/catch 或者 rejected promise 的情況。

為什么：還用解釋嗎?

嚴格約束

no-unnecessary-boolean-literal-compare

不允許對布爾類型變量與 true / false 的 === 比較，如：

declare const someCondition: boolean; 
if (someCondition === true) { 
} 

為什么：首先，記住我們是在寫 TypeScript，所以不要想著你的變量值還有可能是 null 所以需要這樣判斷，如果真的發生了，那么說明你的 TS 類型標注不對哦。而且，此規則的配置項最多允許 boolean | null 這樣的值與 true / false 進行比較，所以還是讓你的類型更精確一點吧。

consistent-type-definitions

TypeScript 支持通過 type 與 interface 聲明對象類型，此規則可將其收束到統一的聲明方式，即僅使用其中的一種。

為什么：先說我是怎么做得：在絕大部分場景下，使用 interface 來聲明對象類型，type 應當用于聲明聯合類型、函數類型、工具類型等，如：

interface IFoo {} 
 
type Partial<T> = { 
  [P in keyof T]?: T[P]; 
}; 
 
type LiteralBool = "true" | "false"; 

原因主要有這么幾點：

• 配合 naming-convention 規則(能夠用于檢查接口是否按照規范命名)，我們能夠在看見 IFoo 時立刻知道它是一個 接口，看見 Bar 時立刻知道它是一個類型別名，配置：

{ 
  "@typescript-eslint/naming-convention": [ 
    "error", 
    { 
      "selector": "interface", 
      "format": ["PascalCase"], 
      "custom": { 
        "regex": "^I[A-Z]", 
        "match": true 
      } 
    } 
  ] 
} 

• 接口在類型編程中的作用非常局限，僅支持 extends、泛型 等簡單的能力，也應當只被用于定義確定的結構體。而 Type Alias 能夠使用除 extends 以外所有常見的映射類型、條件類型等類型編程語法。同時，“類型別名”的含義也意味著你實際上是使用它來歸類類型(聯合類型)、抽象類型(函數類型、類類型)。

method-signature-style

方法簽名的聲明方式有 method 與 property 兩種，區別如下：

// method 
interface T1 { 
  func(arg: string): number; 
} 
 
// property 
interface T2 { 
  func: (arg: string) => number; 
} 

此規則將聲明方式進行約束，推薦使用第二種的 property 方式。

為什么：首先，這兩種方式被稱為 method 與 property 很明顯是因為其對應的寫法，method 方式類似于在 Class 中定義方法，而 property 則是就像定義普通的接口屬性，只不過它的值是函數類型。推薦使用 property 的最重要原因是，通過使用 屬性 + 函數值 的方式定義，作為值的函數的類型能享受到更嚴格的類型校驗( `strictFunctionTypes`[4])，此配置會使用逆變(contravariance)而非協變(covariance)的方式進行函數參數的檢查，關于協變與逆變我后續會單獨的寫一篇文章，這里暫時不做展開，如果你有興趣，可以閱讀 TypeScript 類型中的逆變協變。

consistent-type-imports

約束使用 import type {} 進行類型的導入，如：

// √ 
import type { CompilerOptions } from "typescript"; 
 
// x 
import { CompilerOptions } from "typescript"; 

為什么：import type 能夠幫助你更好的組織你的項目頭部的導入結構(雖然 TypeScript 4.5 支持了類型與值的混合導入：import { foo, type Foo }，但還是推薦通過拆分值導入與類型導入語句來獲得更清晰地項目結構)。值導入與類型導入在 TypeScript 中使用不同的堆空間來存放，因此無須擔心循環依賴(所以你可以父組件導入子組件，子組件導入定義在父組件中的類型這樣)。

一個簡單的、良好組織了導入語句的示例：

import { useEffect } from "react"; 
 
import { Button, Dialog } from "ui"; 
import { ChildComp } from "./child"; 
 
import { store } from "@/store"; 
import { useCookie } from "@/hooks/useCookie"; 
import { SOME_CONSTANTS } from "@/utils/constants"; 
 
import type { Foo } from "@/typings/foo"; 
import type { Shared } from "@/typings/shared"; 
 
import styles from "./index.module.scss"; 

restrict-template-expressions

模板字符串中的計算表達式其返回值必須是字符串，此規則可以被配置為允許數字、布爾值、可能為 null 的值以及正則表達式，或者你也可以允許任意的值，但這樣就沒意思了...

為什么：在模板表達式中非字符串與數字以外的值很容易帶來潛在的問題，如：

const arr = [1, 2, 3]; 
const obj = { name: "linbudu" }; 
 
// 'arr: 1,2,3' 
const str1 = `arr: ${arr}`; 
// 'obj: [object Object]' 
const str2 = `obj: ${obj}`; 

無論哪種情況都不會是你想看到的，因為這實際上已經脫離了你的掌控。推薦在規則配置中僅開啟 allowNumber 來允許數字，而禁止掉其他的類型，你所需要做得應當是在把這個變量填入模板字符串中時進行一次具有實際邏輯的轉化。

switch-exhaustiveness-check

switch 的判定條件為 聯合類型 時，其每一個類型分支都需要被處理。如：

type PossibleTypes = "linbudu" | "qiongxin" | "developer"; 
 
let value: PossibleTypes; 
let result = 0; 
 
switch (value) { 
  case "linbudu": { 
    result = 1; 
    break; 
  } 
  case "qiongxin": { 
    result = 2; 
    break; 
  } 
  case "developer": { 
    result = 3; 
    break; 
  } 
} 

為什么：工程項目中經常出現的，導致問題發生的原因就是有部分功能邏輯點僅通過口口相傳，只看代碼你完全不知道自己還漏了什么地方。如聯合類型變量中每一條類型分支可能都需要特殊的處理邏輯。

你也可以通過 TypeScript 中的 never 類型來實現實際代碼的檢驗：

const strOrNumOrBool: string | number | boolean = false; 
 
if (typeof strOrNumOrBool === "string") { 
  console.log("str!"); 
} else if (typeof strOrNumOrBool === "number") { 
  console.log("num!"); 
} else if (typeof strOrNumOrBool === "boolean") { 
  console.log("bool!"); 
} else { 
  const _exhaustiveCheck: never = strOrNumOrBool; 
  throw new Error(`Unknown input type: ${_exhaustiveCheck}`); 
} 

這里通過編譯時與運行時做了兩重保障，確保為聯合類型新增類型分支時也需要被妥善的處理，你可以參考開頭的 never 類型 文章了解更多 never 相關的使用。除了聯合類型以外，你還可以通過 never 類型來確保每一個枚舉成員都需要處理。

enum PossibleType { 
  Foo = "Foo", 
  Bar = "Bar", 
  Baz = "Baz", 
} 
 
function checker(input: PossibleType) { 
  switch (input) { 
    case PossibleType.Foo: 
      console.log("foo!"); 
      break; 
    case PossibleType.Bar: 
      console.log("bar!"); 
      break; 
    case PossibleType.Baz: 
      console.log("baz!"); 
      break; 
    default: 
      const _exhaustiveCheck: never = input; 
      break; 
  } 
} 

以上就是我們目前在使用的部分規則，還有一批規則或是涉及到高度的定制或是適用場景狹窄，這里就不做列舉了。如果你有什么想法，歡迎與我一起交流，但請注意：我不是在灌輸你一定要使用什么規則，我只是在分享我們使用的規則以及考量，因此在留言前請確認不要屬于此類觀點，感謝你的閱讀。

參考資料

[1]QCon+ 專題：TypeScript 在中大型項目中的落地實踐: https://qconplus.infoq.cn/2021/beijing2nth/track/1240

[2]淘寶店鋪 TypeScript 研發規約落地: https://qconplus.infoq.cn/2021/beijing2nth/presentation/4161

[3]proposal-error-cause: https://github.com/tc39/proposal-error-cause

[4]strictFunctionTypes: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-6.html#strict-function-types