2025年TypeScript已經不夠用了，搭配這個每周下載2000萬次的神器使用，完美！

作者：前端充電寶 2025-03-07 08:33:11

開發前端

在 2025 年，僅依賴TypeScript的靜態檢查已不足以應對復雜應用的挑戰。Zod 通過運行時驗證、類型強制、錯誤處理等特性，與TypeScript形成完美互補。兩者的結合不僅降低了開發成本，更大幅提升了應用的健壯性與安全性。

為什么 TypeScript “不夠用”？

TypeScript作為JavaScript的超集，憑借靜態類型檢查在開發階段極大提升了代碼的健壯性。然而，隨著應用復雜度的提升，其局限性愈發明顯：

? 僅靜態檢查：TypeScript的類型僅在編譯時生效，運行時無法驗證外部輸入（如API、表單數據）是否符合類型預期，可能導致運行時錯誤。

? 無法處理動態數據：如用戶提交的JSON數據、第三方接口返回的字段等，若未嚴格匹配類型定義，程序可能崩潰。

? 缺乏運行時驗證邏輯：例如密碼長度、郵箱格式等業務規則，需開發者手動編寫額外驗證代碼，增加維護成本。

而 Zod——這個周下載量近 2000 萬的新星工具——正是為了解決這些問題而生。

圖片

Zod 是什么？

Zod 是一個 TypeScript 優先的模式聲明和驗證庫，專為開發者在運行時對數據進行類型驗證而設計，可以彌補 TypeScript 僅提供靜態類型檢查的不足。它允許開發者以聲明式的方式定義數據的結構和規則，并在運行時對數據進行驗證，確保數據的正確性和一致性。

Zod 的核心優勢在于它與 TypeScript 的無縫集成，能夠從定義的模式中自動推斷 TypeScript 類型，從而在編譯時和運行時都提供類型安全保障。它的設計理念是“一次定義，處處使用”，既減少了代碼冗余，又提升了開發效率和代碼健壯性。

Zod 提供了許多強大的功能，使其在數據驗證領域脫穎而出。以下是它的主要特點：

? 類型推斷：Zod 可以從定義的模式中自動推斷 TypeScript 類型，開發者無需手動編寫重復的類型聲明。例如，定義一個對象模式后，可以直接從中獲取對應的 TypeScript 類型，減少手動維護類型的工作量。

? 靈活的驗證規則：Zod 支持多種數據類型（如字符串、數字、對象、數組、聯合類型等）和豐富的驗證規則。它通過鏈式 API 提供直觀的語法，讓開發者能夠輕松定義復雜的驗證邏輯。

? 詳細的錯誤消息：當數據驗證失敗時，Zod 會返回清晰且用戶友好的錯誤信息，具體指出哪個字段不符合要求以及原因。這大大方便了調試和錯誤處理。

? 與 TypeScript 無縫集成：Zod 的設計與 TypeScript 高度契合，幾乎沒有額外的學習成本。它增強了類型安全，幫助開發者在開發過程中更早地發現潛在問題。

? 強大的社區支持：Zod 擁有活躍的社區和豐富的生態系統，許多流行框架（如 Next.js、React Hook Form 等）都提供了與 Zod 的集成，進一步擴展了它的應用場景。

? 輕量且無依賴：Zod 是一個輕量級的庫，沒有外部依賴，易于集成到任何 TypeScript 項目中。

? 可擴展性：Zod 支持自定義驗證器和模式，開發者可以根據項目需求擴展其功能，適應更復雜的驗證場景。

Zod 怎么用？

安裝 Zod

在使用 Zod 之前需要先安裝它。可以通過以下命令使用 npm 安裝：

npm install zod

基本用法

Zod 的核心概念是 schema（模式），它用于定義數據的結構和驗證規則。以下是一些常見的基本用法：

基本類型

Zod 支持多種基本數據類型，例如字符串、數字和布爾值：

import { z } from 'zod';

// 定義一個字符串 schema
const stringSchema = z.string();

// 定義一個數字 schema
const numberSchema = z.number();

// 定義一個布爾值 schema
const booleanSchema = z.boolean();

對象

使用 z.object 可以定義對象的結構：

const userSchema = z.object({
  name: z.string(),
  age: z.number(),
  isActive: z.boolean(),
});

數組

使用 z.array 定義數組及其元素的類型：

const stringArraySchema = z.array(z.string()); // 字符串數組
const numberArraySchema = z.array(z.number()); // 數字數組

聯合類型

Zod 支持聯合類型，允許數據是多種類型中的一種：

const stringOrNumberSchema = z.union([z.string(), z.number()]);

可選和可空類型

可以用 .optional() 和 .nullable() 定義可選或可為空的字段：

const optionalStringSchema = z.string().optional(); // 可選字符串
const nullableStringSchema = z.string().nullable(); // 可為空字符串

數據驗證

定義好 schema 后，可以使用 parse 方法驗證數據。如果數據符合 schema，parse 返回驗證后的數據；否則會拋出 ZodError。

const data = { name: 'John', age: 30, isActive: true };

try {
  const validatedData = userSchema.parse(data);
  console.log('數據有效:', validatedData);
} catch (err) {
  if (err instanceof z.ZodError) {
    console.log('數據無效:', err.errors);
  }
}

當驗證失敗時，Zod 會拋出 ZodError，其中包含詳細的錯誤信息。例如：

const invalidData = { name: 'John', age: '30' }; // age 應該是 number

try {
  userSchema.parse(invalidData);
} catch (err) {
  if (err instanceof z.ZodError) {
    console.log('錯誤信息:', err.errors);
  }
}

輸出會指出 age 字段的類型錯誤。

類型推斷

Zod 的一個亮點是能從 schema 自動推斷 TypeScript 類型，使用 z.infer 獲取對應的類型：

type User = z.infer<typeof userSchema>;
// User 類型為 { name: string; age: number; isActive: boolean }

這使得你在開發時既能享受類型安全，又能在運行時驗證數據。

高級用法

自定義驗證

可以使用 .refine 添加自定義驗證邏輯：

const passwordSchema = z.string().refine(
  (val) => val.length >= 8,
  { message: '密碼至少需要8個字符' }
);

數據轉換

使用 .transform 在驗證時轉換數據：

const stringToNumberSchema = z.string().transform((val) => parseInt(val, 10));

驗證 "123" 時會返回 123。

嵌套 schema

可以在 schema 中嵌套其他 schema：

const addressSchema = z.object({
  street: z.string(),
  city: z.string(),
});

const userWithAddressSchema = z.object({
  name: z.string(),
  address: addressSchema,
});

Zod 使用場景

Zod 在需要運行時數據驗證的場景中非常有用，例如：

? 表單驗證：確保用戶輸入的數據符合預期格式和規則。

? API 響應驗證：驗證后端返回的數據結構和類型是否符合預期。

表單驗證

在一個用戶注冊頁面中，我們需要驗證用戶輸入的以下字段：

? 姓名：必須是字符串，長度至少為 2 個字符。

? 電子郵件：必須是有效的郵箱格式。

? 密碼：必須是字符串，長度至少為 8 個字符，且包含至少一個字母和一個數字。

代碼實現如下：

1. 定義模式：使用 Zod 定義一個模式來描述這些規則，并推斷 TypeScript 類型：

import { z } from'zod';

// 定義用戶表單數據的 schema
constUserSchema = z.object({
name: z.string().min(2, '姓名至少需要2個字符'),
email: z.string().email('請輸入有效的電子郵件地址'),
password: z.string()
    .min(8, '密碼至少需要8個字符')
    .regex(/[a-zA-Z]/, '密碼必須包含至少一個字母')
    .regex(/[0-9]/, '密碼必須包含至少一個數字'),
});

// 推斷 TypeScript 類型
typeUser = z.infer<typeofUserSchema>;

2. HTML 表單：

<!DOCTYPE html>
<html lang="zh">
<head>
<meta charset="UTF-8">
<title>用戶注冊表單</title>
</head>
<body>
<h1>用戶注冊</h1>
<form id="registerForm">
    <div>
      <label for="name">姓名:</label>
      <input type="text" id="name" name="name" required />
    </div>
    <div>
      <label for="email">電子郵件:</label>
      <input type="email" id="email" name="email" required />
    </div>
    <div>
      <label for="password">密碼:</label>
      <input type="password" id="password" name="password" required />
    </div>
    <button type="submit">提交</button>
</form>
<div id="message"></div>

<script type="module" src="script.ts"></script>
</body>
</html>

3. 驗證用戶輸入：以下是處理表單提交并使用 Zod 驗證的代碼：

// 獲取表單和消息元素
const form = document.getElementById('registerForm') asHTMLFormElement;
const messageDiv = document.getElementById('message') asHTMLDivElement;

// 表單提交事件處理
form.addEventListener('submit', (event) => {
  event.preventDefault(); // 阻止默認提交行為

// 從表單中收集數據
const formData = newFormData(form);
const userData = {
    name: formData.get('name') asstring,
    email: formData.get('email') asstring,
    password: formData.get('password') asstring,
  };

// 使用 Zod 驗證數據
try {
    UserSchema.parse(userData);
    messageDiv.textContent = '用戶數據有效！提交成功。';
    messageDiv.style.color = 'green';
    console.log('用戶數據有效:', userData);
  } catch (err) {
    if (err instanceof z.ZodError) {
      const errorMessages = err.errors.map((error) => error.message).join('; ');
      messageDiv.textContent = `用戶數據無效: ${errorMessages}`;
      messageDiv.style.color = 'red';
      console.log('用戶數據無效:', err.errors);
    }
  }
});

4. 錯誤信息：對于無效數據，Zod 會返回詳細的錯誤信息：

用戶數據無效: [
  { code: 'too_small', path: ['name'], message: '姓名至少需要2個字符' },
  { code: 'invalid_string', path: ['email'], message: '請輸入有效的電子郵件地址' },
  { code: 'too_small', path: ['password'], message: '密碼至少需要8個字符' },
  { code: 'custom', path: ['password'], message: '密碼必須包含至少一個數字' }
]

API 響應驗證

假設需要從后端 API 獲取用戶信息，預期的響應結構如下：

? id：數字類型，用戶 ID。

? name：字符串類型，用戶姓名。

? email：字符串類型，用戶郵箱。

? isActive：布爾類型，用戶是否活躍。