解鎖TypeScript的潛力：改進(jìn)標(biāo)準(zhǔn)庫類型
在 TypeScript 項(xiàng)目中，我們的編寫代碼并不是唯一的代碼。標(biāo)準(zhǔn)庫和運(yùn)行環(huán)境也會(huì)參與類型檢查。這些包括在全局范圍內(nèi)可用的JavaScript方法和Web平臺(tái)API，包括用于處理數(shù)組、window對(duì)象、Fetch API等方法。本文將探討TypeScript標(biāo)準(zhǔn)庫最常見的問題以及編寫更安全、可靠的代碼的方法！
1、TypeScript 標(biāo)準(zhǔn)庫的問題
Summer IS HERE
TypeScript的標(biāo)準(zhǔn)庫在很大程度上提供了高質(zhì)量的類型定義，但是一些廣泛使用的 API 的類型聲明可能過于寬松或過于嚴(yán)格。
過于寬松類型的最常見問題是使用 any 而不是更精確的類型，比如 unknown。在標(biāo)準(zhǔn)庫中，F(xiàn)etch API 是導(dǎo)致類型安全問題最常見的來源。json()方法返回的是 any 類型的值，這可能導(dǎo)致運(yùn)行時(shí)錯(cuò)誤和類型不匹配，同樣的情況也適用于JSON.parse方法。
async function fetchPokemons() {
const response = await fetch('https://pokeapi.co/api/v2/pokemon');
const data = await response.json();
return data;
}
const pokemons = await fetchPokemons();
// ^? any
pokemons.data.map(pokemon => pokemon.name);
// ^ TypeError: Cannot read properties of undefined另一方面，有一些API的類型聲明過于限制，可能導(dǎo)致開發(fā)體驗(yàn)較差。例如，Array.filter方法的工作方式與直覺相反，需要手動(dòng)進(jìn)行類型轉(zhuǎn)換或編寫類型保護(hù)。
// filteredArray 的類型是 Array<number | undefined>。
const filteredArray = [1, 2, undefined].filter(Boolean);
// filteredArray的類型是 Array<number>
const filteredArray = [1, 2, undefined].filter(
(item): item is number => Boolean(item)
);沒有簡單的方法來升級(jí)或替換標(biāo)準(zhǔn)庫的類型聲明，因?yàn)樗念愋投x是隨 TypeScript 編譯器一起提供的。然而，如果想充分利用 TypeScript，有多種方法可以解決這個(gè)問題。
下面來以 Fetch API 為例探討一些選項(xiàng)。
2、使用類型斷言
Summer IS HERE
一個(gè)快速解決方案是手動(dòng)指定類型。為了做到這一點(diǎn)，需要描述響應(yīng)的格式并將any類型轉(zhuǎn)換為所需的類型。這樣就可以將對(duì)any的使用限制在代碼庫的一小部分中，比在整個(gè)程序中都使用返回的any類型要好很多。
interface PokemonListResponse {
count: number;
next: string | null;
previous: string | null;
results: Pokemon[];
}
interface Pokemon {
name: string;
url: string;
}
async function fetchPokemons() {
const response = await fetch('https://pokeapi.co/api/v2/pokemon');
const data = await response.json() as PokemonListResponse;
return data;
}
const pokemons = await fetchPokemons();
// ^? PokemonListResponse另外，TypeScript 現(xiàn)在將會(huì)突出顯示對(duì)不存在字段的訪問的錯(cuò)誤。然而，類型轉(zhuǎn)換給我們帶來了額外的責(zé)任，即準(zhǔn)確描述從服務(wù)端返回的類型。
pokemons.data.map(pokemon => pokemon.name);
// ^ Error: “Pokemon List Response”類型中不存在屬性“data”
// 應(yīng)該在這里使用 'results' 字段類型斷言可能存在風(fēng)險(xiǎn)，應(yīng)謹(jǐn)慎使用。如果斷言不正確，可能會(huì)導(dǎo)致意外行為。例如，在描述類型時(shí)容易犯錯(cuò)，比如忽略字段可能為null或undefined的情況。
3、使用類型保護(hù)
Summer IS HERE
我們可以通過首先將any強(qiáng)制轉(zhuǎn)換為unknown來增強(qiáng)上述解決方案。這清楚地表明 fetch 函數(shù)可以返回任何類型的數(shù)據(jù)。然后需要通過編寫類型保護(hù)來驗(yàn)證響應(yīng)是否具有需要的數(shù)據(jù)，如下所示：
function isPokemonListResponse(data: unknown): data is PokemonListResponse {
if (typeof data !== 'object' || data === null) return false;
if (typeof data.count !== 'number') return false;
if (data.next !== null && typeof data.next !== 'string') return false;
if (data.previous !== null && typeof data.previous !== 'string') return false;
if (!Array.isArray(data.results)) return false;
for (const pokemon of data.results) {
if (typeof pokemon.name !== 'string') return false;
if (typeof pokemon.url !== 'string') return false;
}
return true;
}類型守衛(wèi)函數(shù)接收一個(gè)具有unknown類型的變量作為輸入。使用is操作符來指定輸出類型，表示已經(jīng)檢查了data變量中的數(shù)據(jù)，并且它具有這種類型。在函數(shù)內(nèi)部，編寫所有必要的檢查，以驗(yàn)證需要的所有字段。
可以使用得到的類型守衛(wèi)來將unknown類型縮小到想要處理的類型。這樣，如果響應(yīng)數(shù)據(jù)格式發(fā)生變化，可以迅速檢測到并在應(yīng)用邏輯中處理該情況。
async function fetchPokemons() {
const response = await fetch('https://pokeapi.co/api/v2/pokemon');
const data = (await response.json()) as unknown;
if (!isPokemonListResponse(data)) {
throw new Error('error');
}
return data;
}
const pokemons = await fetchPokemons();
// ^? PokemonListResponse然而，編寫類型守衛(wèi)可能會(huì)很繁瑣，特別是在處理大量數(shù)據(jù)時(shí)。此外，在類型守衛(wèi)中犯錯(cuò)的風(fēng)險(xiǎn)很高，這等同于在類型定義本身上犯錯(cuò)。
4、使用 Zod 庫
Summer IS HERE
為了簡化類型保護(hù)的編寫，可以使用 Zod 等數(shù)據(jù)驗(yàn)證庫。使用 Zod，可以定義一個(gè)數(shù)據(jù)模式，然后調(diào)用一個(gè)函數(shù)來根據(jù)該模式檢查數(shù)據(jù)格式。
import { z } from 'zod';
const schema = z.object({
count: z.number(),
next: z.string().nullable(),
previous: z.string().nullable(),
results: z.array(
z.object({
name: z.string(),
url: z.string(),
})
),
});這類庫最初是以TypeScript為目標(biāo)開發(fā)的。它們?cè)试S我們只需一次描述數(shù)據(jù)模式，然后自動(dòng)生成類型定義。這消除了手動(dòng)編寫TypeScript接口的需要，并避免了重復(fù)工作。
type PokemonListResponse = z.infer<typeof schema>;這個(gè)函數(shù)本質(zhì)上就像一個(gè)類型守衛(wèi)，而我們無需手動(dòng)編寫它。
async function fetchPokemons() {
const response = await fetch('https://pokeapi.co/api/v2/pokemon');
const data = (await response.json()) as unknown;
return schema.parse(data);
}
const pokemons = await fetchPokemons();
// ^? PokemonListResponse因此，我們得到了一種可靠的解決方案，不留下任何犯錯(cuò)的機(jī)會(huì)。由于不再手動(dòng)編寫類型定義，因此無法出現(xiàn)類型定義的錯(cuò)誤。類型守衛(wèi)也不會(huì)出現(xiàn)錯(cuò)誤。模式中可能會(huì)出現(xiàn)錯(cuò)誤，但可以在開發(fā)過程中察覺到這些錯(cuò)誤。
5、Zod 的替代品
Summer IS HERE
Zod有許多不同的替代品，它們?cè)诠δ堋⒗壌笮『托阅苌嫌兴鶇^(qū)別。對(duì)于每個(gè)應(yīng)用程序，您可以選擇最合適的選項(xiàng)。
例如，superstruct 庫是Zod的一個(gè)更輕量級(jí)的替代方案。由于該庫相對(duì)較小（13.1 kB 對(duì)比 3.4 kB），因此更適合在客戶端使用。
typia 庫是一種稍微不同的方法，它采用提前編譯的方式。由于編譯階段，數(shù)據(jù)驗(yàn)證的速度更快。這對(duì)于大量數(shù)據(jù)或服務(wù)端重型代碼特別重要。
6、解決根本問題
Summer IS HERE
使用 Zod 等庫進(jìn)行數(shù)據(jù)驗(yàn)證可以幫助克服 TypeScript 標(biāo)準(zhǔn)庫中任何類型的問題。但是，了解返回 any 的標(biāo)準(zhǔn)庫方法仍然很重要，并在使用這些方法時(shí)將這些類型替換為unknown。
理想情況下，標(biāo)準(zhǔn)庫應(yīng)該使用unknown類型而不是any。這將使編譯器能夠建議所有需要類型保護(hù)的地方。幸運(yùn)的是，TypeScript 的聲明合并功能提供了這種可能性。
在 TypeScript 中，接口有一個(gè)有用的功能，即同名接口的多個(gè)聲明將合并為一個(gè)聲明。例如，如果有一個(gè)帶有name字段的 User 接口，然后聲明另一個(gè)帶有age字段的 User 接口，則生成的 User 接口將同時(shí)具有name和age字段。
interface User {
name: string;
}
interface User {
age: number;
}
const user: User = {
name: 'CUGGZ',
age: 25,
};這個(gè)特性不僅在單個(gè)文件內(nèi)有效，而是在整個(gè)項(xiàng)目范圍內(nèi)全局有效。這意味著可以使用這個(gè)特性來擴(kuò)展 Window 類型，甚至是擴(kuò)展外部庫的類型，包括標(biāo)準(zhǔn)庫。
declare global {
interface Window {
sayHello: () => void;
}
}
window.sayHello();
// ^ TypeScript 現(xiàn)在知道這個(gè)方法了通過使用聲明合并，可以完全解決TypeScript標(biāo)準(zhǔn)庫中 any 類型的問題。
7、Fetch API 更好的類型
Summer IS HERE
為了改進(jìn)標(biāo)準(zhǔn)庫中的 Fetch API，需要更正 json() 方法的類型，以便它始終返回 unknown 而不是any。首先，確定json方法是 Response 接口的一部分。
interface Response extends Body {
readonly headers: Headers;
readonly ok: boolean;
readonly redirected: boolean;
readonly status: number;
readonly statusText: string;
readonly type: ResponseType;
readonly url: string;
clone(): Response;
}在Response的方法中找不到j(luò)son()方法。相反，可以看到 Response 接口繼承自 Body 接口。因此，查看 Body 接口以找到需要的方法。可以看到，json()方法實(shí)際上返回any類型。
interface Body {
readonly body: ReadableStream<Uint8Array> | null;
readonly bodyUsed: boolean;
arrayBuffer(): Promise<ArrayBuffer>;
blob(): Promise<Blob>;
formData(): Promise<FormData>;
text(): Promise<string>;
json(): Promise<any>;
}為了解決這個(gè)問題，可以在項(xiàng)目中再定義一次 Body 接口，如下所示：
declare global {
interface Body {
json(): Promise<unknown>;
}
}由于聲明合并， json()方法現(xiàn)在將始終返回 unknown 類型。
async function fetchPokemons() {
const response = await fetch('https://pokeapi.co/api/v2/pokemon');
const data = await response.json();
// ^? unknown
return data;
}8、JSON.parse 更好的類型
Summer IS HERE
同樣，我們可以修復(fù)JSON解析的問題。默認(rèn)情況下，parse()方法返回any類型，這可能會(huì)在使用解析后的數(shù)據(jù)時(shí)導(dǎo)致運(yùn)行時(shí)錯(cuò)誤。
const data = JSON.parse(text);
// ^? any為了解決這個(gè)問題，我們需要知道 parse() 方法是 JSON 接口的一部分。然后可以在項(xiàng)目中聲明類型，如下所示：
declare global {
interface JSON {
parse(
text: string,
reviver?: (this: any, key: string, value: any) => any
): unknown;
}
}現(xiàn)在，JSON 解析總是返回unknow類型，這可以帶來更安全、更易于維護(hù)的代碼庫。
const data = JSON.parse(text);
// ^? unknown9、Array.isArray 更好的類型
Summer IS HERE
另一個(gè)常見的例子是檢查變量是否是數(shù)組。默認(rèn)情況下，此方法返回包含any類型的數(shù)組，基本上與使用any沒有區(qū)別。
if (Array.isArray(userInput)) {
console.log(userInput);
// ^? any[]
}這里可以擴(kuò)展數(shù)組構(gòu)造函數(shù)的類型，如下所示，該方法現(xiàn)在返回一個(gè)包含unknown類型的數(shù)組，這樣更安全和準(zhǔn)確。
declare global {
interface ArrayConstructor {
isArray(arg: any): arg is unknown[];
}
}
if (Array.isArray(userInput)) {
console.log(userInput);
// ^? unknown[]
}10、structuredClone 更好的類型
Summer IS HERE
最近引入的克隆對(duì)象方法 structuredClone 也返回 any。
const user = {
name: 'John',
age: 30,
};
const copy = structuredClone(user);
// ^? any修復(fù)這個(gè)問題和前面的方法一樣。不過，在這種情況下，需要添加一個(gè)新的函數(shù)簽名而不是擴(kuò)展接口。幸運(yùn)的是，聲明合并對(duì)函數(shù)也同樣適用。因此，可以按照以下方式修復(fù)這個(gè)問題：
declare global {
declare function structuredClone<T>(value: T, options?: StructuredSerializeOptions): T;
}現(xiàn)在克隆的對(duì)象將具有與原始對(duì)象具有相同的類型。
const user = {
name: 'John',
age: 30,
};
const copy = structuredClone(user);
// ^? { name: string, age: number }11、Array.filter 更好的類型
Summer IS HERE
聲明合并不僅對(duì)修復(fù)any類型的問題很有用，還可以改進(jìn)標(biāo)準(zhǔn)庫的易用性。下面來看一下Array.filter方法的例子。
const filteredArray = [1, 2, undefined].filter(Boolean);
// ^? Array<number | undefined>可以讓 TypeScript 在應(yīng)用 Boolean 過濾函數(shù)后自動(dòng)縮小數(shù)組類型。為此，需要擴(kuò)展 Array 接口，如下所示：
type NonFalsy<T> = T extends false | 0 | "" | null | undefined | 0n ? never : T;
declare global {
interface Array<T> {
filter(predicate: BooleanConstructor, thisArg?: any): Array<NonFalsy<T>>;
}
}現(xiàn)在可以使用filter的簡寫形式，并獲得正確的數(shù)據(jù)類型作為結(jié)果。
12、ts-reset
Summer IS HERE
TypeScript 的標(biāo)準(zhǔn)庫包含超過 1000 個(gè) any 類型的實(shí)例。在使用嚴(yán)格類型的代碼時(shí)，有很多地方可以改善開發(fā)體驗(yàn)。避免手動(dòng)修復(fù)標(biāo)準(zhǔn)庫的一種解決方案是使用 ts-reset 庫。它易于使用，只需在項(xiàng)目中導(dǎo)入一次。
import "@total-typescript/ts-reset";該庫相對(duì)較新，因此它對(duì)標(biāo)準(zhǔn)庫的修復(fù)還沒有想要的那么多。然而，我相信這只是一個(gè)開始。值得注意的是，ts-reset 僅包含對(duì)全局類型的安全更改，不會(huì)導(dǎo)致潛在的運(yùn)行時(shí)錯(cuò)誤。
13、避免在庫中使用
Summer IS HERE
改進(jìn) TypeScript 的標(biāo)準(zhǔn)庫有很多好處。然而，值得注意的是，重新定義標(biāo)準(zhǔn)庫的全局類型限制了這種方法僅適用于應(yīng)用。不適用于庫，因?yàn)槭褂眠@樣的庫會(huì)意外地改變應(yīng)用的全局類型的行為。
一般來說，建議避免在庫中修改 TypeScript 的標(biāo)準(zhǔn)庫類型。相反，可以使用靜態(tài)分析工具在代碼質(zhì)量和類型安全方面獲得類似的結(jié)果，這適用于庫開發(fā)。
14、總結(jié)
Summer IS HERE
TypeScript的標(biāo)準(zhǔn)庫是TypeScript編譯器的一個(gè)關(guān)鍵組成部分，提供了一系列內(nèi)置類型，用于處理JavaScript和Web平臺(tái)API。然而，標(biāo)準(zhǔn)庫并不完美，其中一些類型聲明存在問題，可能導(dǎo)致代碼中的類型檢查質(zhì)量較低。本文探討了一些TypeScript標(biāo)準(zhǔn)庫常見的問題以及編寫更安全、更可靠的代碼的方法。
通過使用類型斷言、類型守衛(wèi)和類似Zod的庫，可以改善代碼庫的類型安全性和代碼質(zhì)量。此外，還可以通過使用聲明合并來修復(fù)問題的根本，從而改善TypeScript標(biāo)準(zhǔn)庫的類型安全性和人性化程度。
