Zod 深度解析：TypeScript 運行時類型安全的終極實踐
作者：萌萌噠草頭將軍
即使你的代碼通過了 TypeScript 類型檢查，來自 API 響應、用戶輸入或配置文件的數據仍可能在運行時導致意外錯誤。Zod? 應運而生，它填補了 TypeScript 類型系統與運行時驗證之間的關鍵空白。
前言
在現代 TypeScript 開發中，我們經常面臨一個關鍵挑戰：編譯時類型安全 ≠ 運行時數據安全。
即使你的代碼通過了 TypeScript 類型檢查，來自 API 響應、用戶輸入或配置文件的數據仍可能在運行時導致意外錯誤。
Zod 應運而生，它填補了 TypeScript 類型系統與運行時驗證之間的關鍵空白。
核心概念解析
類型安全的三層架構
- 靜態類型：TypeScript 編譯時檢查
- 運行時驗證：Zod 的數據校驗
- 類型生成：z.infer 自動推導
Schema 即真理來源（Single Source of Truth）
Zod 的核心理念是：
// 定義一次，多處使用
const UserSchema = z.object({
id: z.string().uuid(),
name: z.string().min(2),
email: z.string().email()
});
type User = z.infer<typeof UserSchema>; // 自動生成類型
function saveUser(user: User) { ... } // 復用類型完整的示例
我們以提交表單數據并發送數據請求為例：
// RegisterForm.tsx
import { useRequest } from"ahooks";
import { Button, Form, Input, message } from"antd";
import React from"react";
import { z } from"zod";
// 定義表單數據的 zod schema
const registerSchema = z.object({
username: z
.string()
.min(3, "用戶名至少3個字符")
.max(20, "用戶名最多20個字符"),
email: z.string().email("請輸入有效的郵箱地址"),
password: z.string().min(6, "密碼至少6個字符"),
});
// 轉換為 TypeScript 類型
type RegisterFormData = z.infer<typeof registerSchema>;
// 模擬 API 請求
const mockRegisterApi = (
data: RegisterFormData
): Promise<{ success: boolean }> => {
returnnewPromise((resolve) => {
setTimeout(() => {
resolve({ success: true });
}, 1000);
});
};
const RegisterForm: React.FC = () => {
const [form] = Form.useForm();
// 使用 useRequest 處理數據請求
const { loading, run } = useRequest(mockRegisterApi, {
manual: true, // 手動觸發
onSuccess: (result) => {
if (result.success) {
message.success("注冊成功");
form.resetFields();
}
},
onError: (error) => {
message.error("注冊失敗: " + error.message);
},
});
// 表單提交處理
const onFinish = async (values: RegisterFormData) => {
try {
// 使用 zod 驗證表單數據
const validatedData = registerSchema.parse(values);
// 觸發 API 請求
await run(validatedData);
} catch (error) {
if (error instanceof z.ZodError) {
// 處理 zod 驗證錯誤
const errors = error.errors.reduce((acc, curr) => {
acc[curr.path[0]] = { validateStatus: "error", help: curr.message };
return acc;
}, {} as any);
form.setFields(
Object.entries(errors).map(([name, value]) => ({ name, ...value }))
);
}
}
};
return (
<div style={{ maxWidth: 400, margin: "0 auto", padding: "20px" }}>
<h2>用戶注冊</h2>
<Form
form={form}
name="register"
onFinish={onFinish}
layout="vertical"
initialValues={{ username: "", email: "", password: "" }}
>
<Form.Item
name="username"
label="用戶名"
rules={[{ required: true, message: "請輸入用戶名" }]}
>
<Input placeholder="請輸入用戶名" />
</Form.Item>
<Form.Item
name="email"
label="郵箱"
rules={[{ required: true, message: "請輸入郵箱" }]}
>
<Input placeholder="請輸入郵箱" />
</Form.Item>
<Form.Item
name="password"
label="密碼"
rules={[{ required: true, message: "請輸入密碼" }]}
>
<Input.Password placeholder="請輸入密碼" />
</Form.Item>
<Form.Item>
<Button type="primary" htmlType="submit" loading={loading} block>
注冊
</Button>
</Form.Item>
</Form>
</div>
);
};
exportdefault RegisterForm;這個示例展示了如何將 zod 的類型安全驗證與 antd 表單和 useRequest 這類的數據請求結合起來，創建一個更加安全的表單提交場景。
最后
Zod 正在成為 TypeScript 生態中數據驗證的事實標準，其設計哲學完美契合現代 TypeScript 應用的開發需求。
責任編輯：武曉燕
來源：
萌萌噠草頭將軍
