Zod 深度解析：TypeScript 運行時類型安全的終極實踐

作者：萌萌噠草頭將軍 2025-04-01 03:10:00

開發前端

即使你的代碼通過了 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 應用的開發需求。

責任編輯：武曉燕來源：萌萌噠草頭將軍