[TypeScript] 使用 Zod 驗證資料

Zod 是一個以 TypeScript 為主的靜態類型驗證套件，主要用途就是定義資料型態並且進行內容驗證。

安裝

Zod 需要 TypeScript 4.5 或以上才能使用，並且需要在 tsconfig.json 中開啟嚴格模式(一般專案預設啟用)

    
{
  "compilerOptions": {
    "strict": true
  }
}
    

使用 npm 安裝套件:

    
npm install zod
    

基本示範

    
import {z} from "zod";

const schema = z.string(); // 定義驗證模式，只能輸入字串

let input = 123; // 輸入內容
let result = schema.safeParse(input); // 驗證

if (!result.success) {
  // 純錯誤訊息
  console.log(result.error.issues[0].message);
  // Expected string, received number

  console.log(result.error.issues);
  /*
  [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "number",
      "path": [],
      "message": "Expected string, received number"
    }
  ]
   */
}
    

通常我們會自訂錯誤訊息:

    
import {z} from "zod";

const schema = z.string({
  required_error: '請輸入內容', // 未填入內容導致的錯誤訊息
  invalid_type_error: '請輸入字串', // 資料型態錯誤導致的錯誤訊息
});

let input = 123; // 輸入內容
let result = schema.safeParse(input); // 驗證

if (!result.success) {
  console.log(result.error.issues[0].message); // 請輸入字串
}
    

註： 除了使用 safeParse 以外還可以使用 parse ，驗證失敗時會直接拋出錯誤。

驗證類型

基本類型驗證有以下幾種:

    
import { z } from "zod";

// 基本類型
z.string();
z.number();
z.bigint();
z.boolean();
z.date();
z.symbol();

// 空
z.undefined();
z.null();
z.void(); // 接受 undefined

// 任何類型
z.any();
z.unknown();

// 不接受任何值
z.never();
    

object 驗證

Zod 也支援 object 的驗證，對於表單之類的驗證非常的實用:

    
import {z} from "zod";

// 定義驗證
const schema = z.object({
  username: z.string()
      .min(3, '使用者名稱至少需要 3 個字元')
      .max(10, '使用者名稱最多 10 個字元'),
  password: z.string()
      .min(8, '密碼至少需要 8 個字元'),
});

// 實際資料
const loginForm = {
  username: '13',
  password: '',
};

// 執行驗證
const result = schema.safeParse(loginForm);

if (!result.success) {

  let usernameError = result.error.formErrors.fieldErrors.username;
  let passwordError = result.error.formErrors.fieldErrors.password;

  if (usernameError) console.log(`usernameError: ${usernameError}`);
  if (passwordError) console.log(`passwordError: ${passwordError}`);
}
    

參考資料：
GitHub - colinhacks/zod
Zod
Colin McDonnell - Designing the perfect Typescript schema validation library