Zod進行TypeScript型別驗證使用詳解

2022-09-30 14:01:55

引言

這篇文章將描述如何使用Zod 為您的專案設定型別驗證。Zod 是一個用於型別宣告和驗證的開源 TypeScript 庫。我們將研究為什麼使用 Zod 進行型別驗證，提供如何使用它的範例，並將其與其他庫進行比較。

什麼是型別驗證，為什麼需要它？

型別驗證是驗證資料結構是否符合特定型別的過程。您可以使用它來確保輸入資料的有效性，以及記錄和執行程式碼的資料結構。

使用型別驗證有兩個主要好處：

執行時的資料完整性：確保資料以正確的格式輸入您的系統有助於避免錯誤並保持資料一致性。雖然 TypeScript 可以幫助您在編譯時確保型別安全，但當您處理來自未知資料（例如伺服器或使用者輸入）的資料時，型別驗證在執行時會大放異彩。
檔案：一個好的型別驗證庫將為您使用的資料結構提供準確的型別定義。型別定義可用於為您的專案生成靜態檔案。

為什麼要使用zod？

雖然有許多 TypeScript 型別校驗庫，但個人認為 Zod 是比較好的之一。在為您的專案選擇庫時，除了其功能集外，您還應考慮其實現細節。

Zod 具有零依賴性，這意味著您可以在沒有任何其他庫的情況下安裝和使用 Zod，它將幫助您保持更小的包大小。
Zod 適用於 Node.js 和所有主流瀏覽器（包括 IE 11）。這使其成為需要支援各種平臺的專案的不錯選擇。
Zod 被設計為 TypeScript 優先，這意味著該庫將自動為您的資料結構推斷靜態 TypeScript 型別。這消除了兩次宣告型別的需要——一次在 Zod 中，一次在 TypeScript 中。它將為您節省大量輸入，並幫助您保持程式碼更改同步。
Zod 的 API 簡潔且可連結。這使得建立複雜的資料型別變得容易。您還可以輕鬆地將更簡單的型別組合成更復雜的資料型別。

使用 Zod 進行型別驗證的範例

Primitives

讓我們看看如何驗證字串。假設我們要驗證使用者輸入的密碼。我們希望密碼是一個非空字串，長度至少為 8 個字元，最多為 32 個字元：

import { z } from "zod";
const stringSchema = z.string().nonempty().min(8).max(32);
stringSchema.parse("");
stringSchema.parse(""); // throws an exception
stringSchema.parse("I am a valid password"); // returns "I am a valid password"

當你執行上面的程式碼時，你會看到 parse 方法丟擲了一個異常。異常將包含一個物件陣列，其中包含ZodError錯誤的詳細描述：

    [
      {
      "code": "too_small",
      "minimum": 1,
      "type": "string",
      "inclusive": true,
      "message": "Should be at least 1 characters",
      "path": []
      },
      {
      "code": "too_small",
      "minimum": 8,
      "type": "string",
      "inclusive": true,
      "message": "Should be at least 8 characters",
      "path": []
      }
    ]

當您嘗試解析有效字串時，parse 將簡單地返回其值。

物件

現在讓我們繼續討論物件。Zod 對驗證巢狀物件結構具有強大的支援。

讓我們建立一個型別來驗證使用者物件。它將包含以下欄位：

姓名
電子郵件
電話號碼

要宣告型別，我們使用z.object() 方法：

    import { z } from "zod";
    const User = z.object({
      email: z.string().email(),
      name: z.string(),
      phoneNumber: z.number()
    });

讓我們嘗試根據我們剛剛建立的型別驗證範例物件：

    const result = User.parse({
      email: "hi@sample.com",
      name: "Hello World"
    });

該parse方法將返回一個包含解析結果的物件。由於我們忘記在範例中提供該phoneNumber欄位，Zod 將丟擲異常，幷包含以下錯誤陣列：

    [
      {
      "code": "invalid_type",
      "expected": "number",
      "received": "undefined",
      "inclusive": true,
      "message": "Required"
      "path": ["phoneNumber"]
      }
    ]

型別推斷

我們還可以從物件中推斷出型別。這是您可以免費獲取屬性的型別定義並在您的程式碼中使用它們的部分：

    type UserType = z.infer<typeof User>;

組合型別

Zod 讓您可以輕鬆地在彼此之上組合複雜的型別，就像您構建樂高積木一樣。

為了證明這一點，讓我們使用User上面的型別物件並構建一個更詳細的具有愛好的使用者物件：

    const User = z.object({
      email: z.string().email(),
      name: z.string(),
      phoneNumber: z.number()
    });
    const Hobby = z.object({
      hobbyName: z.string().min(1)
    });
    const Hobbyist = User.merge(Hobby);
    const result = Hobbyist.safeParse({
      email: "hi@sample.com",
      name: "Hello World",
      phoneNumber: 123
    });

通過組合我們的兩個型別物件，我們建立了一個新型別物件，您可以使用它來驗證使用者物件是否具有適當的愛好欄位。

在現有物件之上組合新物件是一種很好的方法，因為它可以幫助您保持資料結構中的所有更改同步。

注意事項

在使用 Zod 進行驗證時，需要牢記幾件事。

安全解析

如果不想讓Zod丟擲異常，當解析失敗時，可以改用該safeParse方法。這將返回一個包含解析結果的物件：

 mySchema.safeParse(""I am a valid password""); // => { success: true; data: "I am a valid password" }    
 mySchema.safeParse(""); // => { success: false; error: ZodError }

無法識別的Key被刪除

預設情況下，Zod 在解析過程中會去除無法識別的key。這意味著任何未知的key都將被忽略。

如果您想通過無法識別的key而不丟失它們，您可以使用該.passthrough()方法。

其他事項

.array() 方法返回一個新的 ZodArray 範例，這意味著呼叫方法的順序很重要。通過切換鏈中呼叫的順序，您可以獲得完全不同的結果：

z.string().optional().array(); // (string | undefined)[]  
z.string().array().optional(); // string[] | undefined

Zod 與其他庫的比較

其他廣泛使用的型別驗證庫也是不錯的選擇，例如 yup 和 io-ts。

以下是您專案的選擇Zod 的一些原因：

TypeScript 首次支援。Zod 在構建時考慮了 TypeScript，並具有一流的支援。這意味著您可以獲得自動完成和出色的 VsCode 支援。
無需額外工作即可為您獲取型別。
易於組合的型別物件 - 通過組合不同的型別物件來構建複雜的驗證規則。
強大的錯誤處理。Zod 具有出色的錯誤處理功能，具有豐富的 API 用於設定錯誤處理流程。
支援 Promise 和函數模式。如果您需要驗證函數或 Promise，Zod 可以滿足您的需求。

結論

在這篇文章中，我們介紹瞭如何使用 Zod 庫進行 TypeScript 型別驗證。我們研究瞭如何建立型別和使用型別來驗證資料結構。我們還看到了使用 Zod 時需要注意的一些事項以及它相對於其他庫的優勢。

有關 Zod 的更多資訊，可以檢視其 Github 頁面上的優秀檔案。

更多關於Zod TypeScript型別驗證的資料請關注it145.com其它相關文章！