Zod 的魔法:為什麼它能「定義一次,享受兩次」?

深入探討 Zod 如何利用 _output 與 z.infer,結束 TypeScript 型別與執行期驗證的長期分裂。

•4 min read
medium

前言

最近回歸職場後,我注意到一個叫做 zod 的工具。

它非常神奇。它不只能用來驗證資料,它的規則竟然還能反過來變成 TypeScript 的型別,解決了很多過去處理型別時的麻煩。

我使用了一陣子後,就對它背後的原理非常好奇:「它究竟是怎麼辦到的?」

在深入探究後,我終於有了初步的理解,所以決定寫下這篇文章,分享我是如何搞懂這一切的。

在 TypeScript 的世界裡,我們一直在追求「類型安全」。但在 API 開發中,我們長期以來都活在一種「分裂」的狀態:

  1. 編譯期 (Compile Time): 我們手動編寫 interface 或 type,讓 VS Code 知道我們的資料長什麼樣子。
  2. 執行期 (Runtime): 我們用 Joi 或其他驗證庫,再寫一套驗證規則,去檢查從前端或 .env 傳來的「不被信任的」資料。

這意味著我們必須維護兩套幾乎一樣的邏輯。只要一邊改了,另一邊忘了改,Bug 就會出現。

Zod,一個「TypeScript-first」的驗證庫,徹底解決了這個問題。它最神奇的地方,就是:「一套規則,兩種享受」。

Zod 的雙重職責

當你寫下這段 Zod Schema:

import { z } from 'zod';
 
// 1. Zod Schema (唯一的「事實來源」)
const UserSchema = z.object({
  username: z.string().min(3),
  email: z.string().email(),
});

UserSchema 這個常數,其實同時扮演著兩種角色:

角色一:執行期的「保全」 (Validator)

這是在程式執行時的角色。UserSchema 是一個真實存在的 JavaScript 物件,它有一個 .parse() 方法。你可以用它來「驗證」真實的資料。

// 執行期:用 .parse() 驗證
try {
  const user = UserSchema.parse({ username: 'al' }); // 👈 這會拋出錯誤
} catch (err) {
  console.error(err); // ZodError: "username" must be at least 3 chars
}

角色二:編譯期的「藍圖」 (Type Definition)

這是在程式編譯時(也就是在 VS Code 裡)的角色。Zod 巧妙地利用了 TypeScript 的類型系統,讓 UserSchema 這個變數本身「攜帶」了它所代表的 TypeScript 類型資訊。

而我們需要一個「鑰匙」來解鎖這個資訊。

解鎖魔法:z.infer 是如何運作的?

z.infer 就是那把「鑰匙」。它是一個只存在於 TypeScript 類型世界的工具。

// 編譯期:用 z.infer 抓取類型
type User = z.infer<typeof UserSchema>;
 
// User 類型被自動推導為:
// {
//   username: string;
//   email: string;
// }

這個「自動推導」的背後,有兩個關鍵的 TypeScript 技術:

1. _output:Zod 藏好的「類型標籤」

Zod 的作者非常聰明。他們在 Zod 函式庫的原始碼中,為每一個驗證器(z.string, z.number...)的類型定義,都加上了一個隱藏的屬性,叫做 _output。

  • z.string() 的類型定義中,藏著 _output: string。
  • z.number() 的類型定義中, 藏著 _output: number。

而 z.object() 這個組合器,會自動「組合」你傳入的所有 _output 標籤,產生一個新的 _output 標籤。

所以,當你定義 UserSchema 時,TypeScript 會自動幫你組合出,UserSchema 這個變數的類型上,攜帶了一個標籤:

_output: { username: string, email: string }

2. extends 和 infer:拆禮物的工具

z.infer<T> 的內部原理,就是如同的「拆禮物」工具:

// Zod 函式庫中的(簡化)定義:
type z.infer<T> =
  T extends { _output: infer O } // 👈 提問 + 填空
  ? O                            // 👈 回傳答案
  : never;

這段程式碼的白話文就是:

  • T extends … (提問):
  • 「嘿 TypeScript,傳進來的 T (也就是 UserSchema 的類型),它是不是一個『帶有 _output 標籤』的禮物盒?」
  • { _output: infer O } (填空):
  • 「如果是!那請你幫我『推斷 (infer)』出 _output 標籤裡面的類型是什麼,並把這個類型放進 O 這個空格裡。」
  • ? O : never (回傳):
  • 「提問成功,O 現在等於 { username: string, email: string }。好,我就把 O 回傳出去。」

結論

Zod 的魔法並非憑空而來,它建立在對 TypeScript 類型系統的深刻理解之上。

它透過在「Schema 物件」上同時附加「執行期驗證邏輯」和「編譯期類型標籤 (_output)」 ,並提供 z.infer 這個「類型讀取器」,完美地實現了「單一事實來源 (Single Source of Truth)」。

你只需要維護 Zod Schema,就能同時確保你的「執行期驗證」和「編譯期類型」100% 同步。這就是 Zod 如此強大且優雅的真正原因。