如何編寫健壯的 TypeScript 庫？
當你用 TypeScript 編寫庫時，你通常不知道這個庫最終將如何被使用。即使你 警告潛在用戶，你編寫這個庫只是針對 TypeScript 用戶，你還是可能會在某個時刻擁有 JavaScript 用戶——或者是因為他們不顧你的警告而使用這個庫，或者是他們因為傳遞性依賴而使用這個庫。這有一個非常重要的后果：你必須將這個庫設計成任何語言的開發者都可以使用！
其主要部分是函數定義和函數體。如果你針對一個純 TypeScript 讀者編寫，那么你只需定義函數類型并信任編譯器處理其它事情。如果你針對一個純 JavaScrpit 讀者編寫，那么你需要記錄那些類型，但在函數中將實際的類型設為unknown并檢查調用方傳遞的內容。
例如，給定如下代碼
- interface Person {
- age: number;
- name?: string;
- }
- function describe(person: Person): string {
- let name = person.name ?? 'someone';
- return `${name} is ${person.age} years old!`;
- }
一個 JS 用戶可能用任何東西來調用describe函數。
正確寫法：
- describe({ name: "chris" })
災難性的錯誤寫法：
- describe("potato");
最常見的 JS 錯誤:
- describe(undefined);
你的庫的 JS 用戶并不是故意這么做的。恰恰相反，在任何足夠大的系統中，很容易將錯誤的參數傳遞給系統中的某個函數。這通常是一個很難避免的錯誤，比如在一個點上做了修改，許多其它地方需要更新，但漏掉了一個點。故意的 JS 開發者會把壞數據發送到你設計精美的 TS API 中。
如果你針對一個純 TypeScript 讀者編寫，那么你只需定義函數類型并信任編譯器處理其它事情
我故意不提 TypeScript 編譯非常嚴格，從一個與 JavaScript 沒有區別的級別到幾乎任何人可能想到的嚴格級別。這意味著，即使是 TypeScript 調用者也應該像 JavaScript 調用者一樣被對待：眾所周知，他們到處亂扔any，忽略了事實上可能是null或undefined的地方。返回上面的示例代碼：
- interface Person {
- age: number;
- name?: string;
- }
- function describe(person: Person): string {
- let name = person.name ?? 'someone';
- return `${name} is ${person.age} years old!`;
- }
在沒有啟用嚴格標識的情況下，TypeScript 用戶可以如下調用describe：
- function cueTheSobbing(data: any) {
- describe(data);
- }
- cueTheSobbing({ breakfastOf: ["eggs", "waffles"] });
或者這樣:
- describe(null);
或者這樣:
- describe({ age: null })
也就是說：JS 調用者大部分會出錯的方式，TS 調用者在關閉嚴格性設置的情況下也會出錯。這意味著故意的 TypeScript 用戶也會用壞數據調用你的庫。而且由于他們依賴其它庫，這很可能不是他們的錯誤，因為這種問題可能發生在依賴圖中的任何地方。
因此，如果問題是我們不能信任數據，那么我們應該怎么做？一個選項是使函數的所有參數實際為unknown，并用 JSDoc 指定它該如何。然而，那樣會使我們失去大量 TS 提供的能力。當與函數交互時，我們即使在內部也不會得到補全或類型錯誤，更不用說我們的庫的用戶。但是正如我們剛剛看到的，我們也不能依賴類型定義來提供函數內部的安全性。不過，我們可以將這幾種方法結合起來：指定類型定義，并將傳入的數據視為實際上的unknown。這確實帶來了運行時開銷——我們稍后將圍繞這個權衡進行詳細討論。現在，我們可以先看看如何檢查類型。
首先，我們會像實際上會從調用者得到真正未知的數據來編寫我們的代碼，因為我們已經確定了這正是我們可能得到的。一旦我們完成了對unknown數據的校驗，我們就能夠將它替換為Person，而且所有東西都應該繼續工作，但是現在我們可以保證它對任何拋給它的數據都能夠工作。
- function describe(person: unknown): string {
- let name = person.name ?? 'someone';
- return `${name} is ${person.age} years old`;
- }
這里有類型錯誤，因為這里的person類型可能是undefined或"potato"或者任何其它類型。我們可以使用 TypeScript 的類型縮小的概念來保證安全。然而，從unknown縮小到特定的對象類型有點兒奇怪，因為如果你簡單地檢查是否typeof somethingUnknown === 'object'，這會將類型縮小到{}，這意味著它不會包含任何我們可能需要的類型。我們會先定義一個isObject輔助函數，它會為我們提供正確的語義：
- function isObject(
- maybeObj: unknown
- ): maybeObj is Record<string | number | symbol, unknown> {
- return typeof maybeObj === 'object' && maybeObj !== null;
- }
我們還需要一種方法來檢查這個對象有沒有指定的屬性。如果in運算符能以這種方式工作就太好了，但不幸的是，它沒有這樣工作。我們也可以內聯這樣做，但是每次都需要類型轉換。我們可以稱之為has，類似于Object.hasOwnProperty方法。由于這還需要檢查isObject返回的類型集——在 JS 中索引一個對象的所有合法類型——我們這里會將其提取到一個新的Key類型。
這個has輔助函數的返回類型告訴類型系統，如果主體為 true，傳入的項目有其原始類型而且它包含我們要檢查的屬性。
- type Key = string | number | symbol;
- function has<K extends Key, T>(
- key: K,
- t: T
- ): t is T & Record<K, unknown> {
- return key in t;
- }
現在我們可以將它們組合成一個類型保護器，來檢查給定對象是否是一個 person：
- function isPerson(value: unknown): value is Person {
- return (
- isObject(value) &&
- has('age', value) && typeof value.age === 'number' &&
- (has('name', value) ? typeof value.name === 'string' : true)
- )
- }
現在，我們可以將所有這些集合到我們函數頂部的一個簡單的檢查中，如果它不合法的話拋出一個有用的錯誤。
- function describe(person: unknown): string {
- if (!isPerson(person)) {
- throw new Error('`describe` requires you to pass a `Person`');
- }
- let name = person.name ?? 'someone';
- return `${name} is ${person.age} years old`;
- }
既然我們已經有了這個功能，我們可以將這里的person類型更新為Person來讓 TypeScript 用戶有更好的體驗。
- function describe(person: Person): string {
- if (!isPerson(person)) {
- throw new Error(
- `'describe' takes a 'Person', but you passed ${JSON.stringify(person)}`
- );
- }
- let name = person.name ?? 'someone';
- return `${name} is ${person.age} years old`;
- }
TypeScript 支持在條件不包含斷言函數時拋出的這種模式泛化，這非常有用。我們可以編寫如下格式：
- function assert(
- predicate: unknown,
- message: string
- ): asserts predicate {
- if (!pred) {
- throw new Error(message);
- }
- }
現在我們的函數變得更簡單：
- function describe(person: Person): string {
- assert(
- isPerson(person),
- `'describe' takes a 'Person', but you passed ${JSON.stringify(person)}`
- );
- let name = person.name ?? 'someone';
- return `${name} is ${person.age} years old`;
- }
到目前為止，一直都還不錯！我們現在保證，無論誰調用describe，無論是從 JS，還是從松散類型的 TS，或是從其它完全不同的語言，它都會做“正確”的事情，在出錯時向調用者提供一個可操作的錯誤。然而，根據我們的限制，這種運行時校驗會開銷過大而不可行。在一個瀏覽器中，我們通過網絡發送的額外代碼積累起來：需要下載更多東西，也需要解析更多東西，這都會減慢我們的 app。在任何環境中，每次與describe函數交互時都會進行額外的運行時檢查。一種選項是利用一些編譯智能來在開發期間而不是在生產構建中提供這些檢查。Babel 允許你將給定函數轉變成 noops，使得它們不完全沒有開銷，但開銷非常小。例如，Ember CLI 提供了一個 Babel 插件將 Ember 的assert函數（其類型與我在上面定義的assert幾乎等同）轉變成 no-ops。你可以將它與任何可以消除無用代碼的工具結合起來，以刪除所有沒有用到的輔助函數！
這種方案的缺點是，生產環境的錯誤的錯誤消息會比較糟糕，并且更難以調試。優點是，在生產環境中，你將上傳更少的代碼且運行時開銷更少。為了使依賴這種assert片段的代碼工作，終端用戶需要將它與任何具有良好的端到端測試覆蓋的功能、UI 組件等相結合。但是不管怎樣，這都是正確的：類型和測試消除了不同類型的 bugs，最好結合使用！
