2025 年 TypeScript 已經不夠用了，搭配這個每周下載 2000 萬次的神器使用，完美！
一、為什么 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 怎么用？
1. 安裝 Zod
在使用 Zod 之前需要先安裝它。可以通過以下命令使用 npm 安裝：
npm install zod2. 基本用法
Zod 的核心概念是 schema（模式），它用于定義數據的結構和驗證規則。以下是一些常見的基本用法：
(1) 基本類型
Zod 支持多種基本數據類型，例如字符串、數字和布爾值：
import { z } from 'zod';
// 定義一個字符串 schema
const stringSchema = z.string();
// 定義一個數字 schema
const numberSchema = z.number();
// 定義一個布爾值 schema
const booleanSchema = z.boolean();(2) 對象
使用 z.object 可以定義對象的結構：
const userSchema = z.object({
name: z.string(),
age: z.number(),
isActive: z.boolean(),
});(3) 數組
使用 z.array 定義數組及其元素的類型：
const stringArraySchema = z.array(z.string()); // 字符串數組
const numberArraySchema = z.array(z.number()); // 數字數組(4) 聯合類型
Zod 支持聯合類型，允許數據是多種類型中的一種：
const stringOrNumberSchema = z.union([z.string(), z.number()]);(5) 可選和可空類型
可以用 .optional() 和 .nullable() 定義可選或可為空的字段：
const optionalStringSchema = z.string().optional(); // 可選字符串
const nullableStringSchema = z.string().nullable(); // 可為空字符串3. 數據驗證
定義好 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 字段的類型錯誤。
4. 類型推斷
Zod 的一個亮點是能從 schema 自動推斷 TypeScript 類型，使用 z.infer 獲取對應的類型：
type User = z.infer<typeof userSchema>;
// User 類型為 { name: string; age: number; isActive: boolean }這使得你在開發時既能享受類型安全，又能在運行時驗證數據。
5. 高級用法
(1) 自定義驗證
可以使用 .refine 添加自定義驗證邏輯：
const passwordSchema = z.string().refine(
(val) => val.length >= 8,
{ message: '密碼至少需要8個字符' }
);(2) 數據轉換
使用 .transform 在驗證時轉換數據：
const stringToNumberSchema = z.string().transform((val) => parseInt(val, 10));驗證 "123" 時會返回 123。
(3) 嵌套 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 響應驗證：驗證后端返回的數據結構和類型是否符合預期。
1. 表單驗證
在一個用戶注冊頁面中，我們需要驗證用戶輸入的以下字段：
- 姓名：必須是字符串，長度至少為 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: '密碼必須包含至少一個數字' }
]2. API 響應驗證
假設需要從后端 API 獲取用戶信息，預期的響應結構如下：
- id：數字類型，用戶 ID。
- name：字符串類型，用戶姓名。
- email：字符串類型，用戶郵箱。
- isActive：布爾類型，用戶是否活躍。
代碼實現如下：
(1) 定義 API 響應模式：使用 Zod 定義 API 響應數據的模式，并推斷 TypeScript 類型：
import { z } from'zod';
// 定義 API 響應數據的 schema
constApiResponseSchema = z.object({
id: z.number(),
name: z.string(),
email: z.string().email(),
isActive: z.boolean(),
});
// 推斷 TypeScript 類型
typeApiResponse = z.infer<typeofApiResponseSchema>;(2) 驗證 API 響應：以下是發起 API 請求并使用 Zod 驗證返回數據的代碼。
// 模擬從后端獲取數據的函數
asyncfunctionfetchUserData(endpoint: string): Promise<void> {
try {
// 發起 API 請求
const response = awaitfetch(endpoint);
if (!response.ok) {
thrownewError(`HTTP error! status: ${response.status}`);
}
// 解析 JSON 數據
const data = await response.json();
// 使用 Zod 驗證數據
const validatedData = ApiResponseSchema.parse(data);
console.log('API 響應有效:', validatedData);
} catch (err) {
if (err instanceof z.ZodError) {
console.log('API 響應無效:', err.errors);
} else {
console.error('請求失敗:', err);
}
}
}
// 示例 1：調用 API 并假設返回有效數據
// 假設后端返回的數據是 { id: 1, name: "Jane Doe", email: "jane@example.com", isActive: true }
console.log('測試有效數據:');
fetchUserData('https://api.example.com/user/1');
// 示例 2：調用 API 并假設返回無效數據
// 假設后端返回的數據是 { id: "1", name: "Jane Doe", email: "jane@example.com", isActive: "true" }
console.log('測試無效數據:');
fetchUserData('https://api.example.com/user/invalid');(3) 錯誤信息：對于無效數據，Zod 會返回類似以下的錯誤信息：
API 響應無效: [
{ code: 'invalid_type', path: ['id'], message: 'Expected number, received string' },
{ code: 'invalid_type', path: ['isActive'], message: 'Expected boolean, received string' }
]五、TypeScript+Zod = 終極類型安全
在 2025 年，僅依賴TypeScript的靜態檢查已不足以應對復雜應用的挑戰。Zod 通過運行時驗證、類型強制、錯誤處理等特性，與TypeScript形成完美互補。兩者的結合不僅降低了開發成本，更大幅提升了應用的健壯性與安全性。
Zod是TypeScript 缺失的那塊拼圖，沒有它，你的類型系統永遠不完整。
