給覺得「光有型別定義還不夠安心」的你

你用 TypeScript 撰寫程式碼，完美地整理了型別定義，編譯錯誤也是零。然而，在執行時，卻因為 API 傳來了預料之外的資料結構，導致應用程式崩潰……。你是否有過這種痛苦的經驗？

使用 Zod 簡化 JSON 驗證

最重要的關鍵在於：TypeScript 的型別僅存在於「編譯時」，一旦程式碼在瀏覽器中執行，這些型別就會消失。這意味著：「確認外部資料是否正確」的唯一方法，就是在「執行期」進行檢查。

Zod：將型別安全帶入「執行期」

這就是 Zod 大顯身手的地方。
Zod 讓你定義資料的「結構描述（Schema，即設計圖）」，並在執行時嚴格檢查資料是否符合該設計圖。

  • 從入口攔截不正確的資料：如果期待的是 string 卻傳來了 null，Zod 會立即拋出錯誤，保護後續的程式邏輯。
  • 同時獲得型別定義：定義好結構描述後，就能利用 z.infer<T> 自動從中提取對應的 TypeScript 型別。

將編寫結構描述的勞力降至「零」

雖然 Zod 非常強大，但要手動編寫與複雜 JSON 匹配的結構描述，仍是一項相當耗時的工作。

本站的 JSON 轉 Zod 轉換工具 旨在消除編寫結構描述的繁瑣感。只需貼上您手邊的 JSON，它就會瞬間為您生成對應的 Zod 結構描述。

基本工作流程

  1. 複製 API 回傳的 JSON 資料。
  2. 貼到工具中，生成 Zod 結構描述（z.object({...})）。
  3. 將生成的程式碼貼回專案，並透過 Schema.parse(data) 開始驗證！
import { z } from 'zod';

// 工具生成的結構描述
const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});

// 同時進行執行期檢查與型別提取
type User = z.infer<typeof UserSchema>;
const safeData = UserSchema.parse(rawData);

API 回應的實務範例

實務上會出現小落差：清單 API 的某個欄位回傳 null、日期以字串回傳、數字 ID 變成字串。

{
  "id": "123",
  "name": "Ada",
  "lastLoginAt": null
}

從這份 JSON 生成的結構描述不會原樣使用，而是依規格調整。若打算把 id 轉成數字，使用 z.coerce.number()；若可接受沒有登入時間，使用 z.string().datetime().nullable()。用工具產生初稿，再讓人只審查邊界情況——這樣能減少手寫錯誤，同時貼合真實 API。

結語

守護資料的邊界，就是守護系統的穩定性。
將「大概沒問題吧」的推測，轉化為使用 Zod 的「確實驗證」。把手動編寫的繁重工作交給工具，讓自己能專注於實作更核心的業務邏輯。

常見問題

有了 TypeScript 型別，還需要 Zod 嗎？

TypeScript 型別只存在於編譯期，執行期就會消失。「來自外部的資料」——外部 API、表單輸入——不保證符合你的型別，因此需要 Zod 這類執行期驗證器。使用 Zod 時，z.infer 也會給你型別，所以不必同時維護型別與驗證兩份。

既然 Zod 也能生成型別，還需要 JSON 轉 TypeScript 嗎？

若需要執行期驗證，用 z.infer 從 Zod 結構描述推導型別是單一來源、較方便的做法。若只需要可信任內部資料的型別、不需驗證，則 JSON 轉 TypeScript 工具 更簡單。依用途選擇即可。

生成的結構描述可以直接使用嗎？

可作為初稿直接使用，但建議依實際 API 規格調整。用 z.coerce.number() 轉換數字字串、.nullable() 處理可為 null 的值、.optional() 處理選填欄位。只讓人審查邊界情況，能減少手寫錯誤。