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

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

使用 Zod 簡化 JSON 驗證

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

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

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

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

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

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

本站的 JSON 轉 Zod 轉換工具 旨在消除編寫結構描述的繁瑣感。只需貼上您手邊的 JSON,它就會瞬間為您生成對應的 Zod 結構描述。若您手上已有 JSON Schema 或 OpenAPI 定義,JSON Schema ⇄ Zod 轉換器 會更精確:值範例無法表達的必填與 format 都會被保留。

基本工作流程

  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);

產生規則:解讀實際的輸出

看看由下面這份 JSON 產生的結構描述,就能知道工具如何推論。

{
  "users": [
    { "id": 1, "name": "Ada", "email": "a@example.com", "score": 10 },
    { "id": 2, "name": "Bob", "score": 9.5, "deletedAt": null }
  ],
  "tags": [],
  "meta": { "created-at": "2026-01-01T00:00:00Z", "page": 1, "note": null },
  "mixed": [1, "a"],
  "empty": {}
}

輸出如下。

import { z } from 'zod';

const schema = z.object({
    users: z.array(z.object({
        id: z.number(),
        name: z.string(),
        email: z.string().optional(),
        score: z.number(),
        deletedAt: z.null().optional(),
    })),
    tags: z.array(z.unknown()),
    meta: z.object({
        "created-at": z.string(),
        page: z.number(),
        note: z.null(),
    }),
    mixed: z.array(z.union([z.number(), z.string()])),
    empty: z.object({}),
});

type Schema = z.infer<typeof schema>;
  • 輸出由 import、const schema = …、type Schema = z.infer<typeof schema> 三部分組成。名稱(schema / Schema)請在產生後改成喜歡的名稱
  • 整數與小數都會變成 z.number()(像 score 這樣 10 與 9.5 混在一起也一樣)。若只想允許整數,請手動改成 z.number().int()
  • 陣列會把所有元素的形狀合併成一個。只有部分元素才有的鍵(email)會變成 .optional()。值只有 null 的鍵(deletedAt)會變成 z.null().optional(),請手動改回實際的型別
  • 混有不同種類值的陣列會變成 z.union([...])。「某個型別,或 null」則使用 .nullable()
  • 空陣列是 z.array(z.unknown()),空物件是 z.object({})。樣本中沒有元素時,無法決定型別
  • 像 created-at 這種無法寫成識別字的鍵,會加上引號輸出
  • 日期時間字串("2026-01-01T00:00:00Z")也是 z.string()。若想用 z.string().datetime() 嚴格驗證,請手動修改

API 回應的實務範例

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

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

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

結語

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

2026 年 11 月新增的功能

  • 同一份 JSON 也能產生 Valibot 結構與 JSON Schema(draft 2020-12)。字串格式選項(日期時間、電子郵件、UUID、URL)與根名稱也會套用。
  • 陣列元素會合併,只出現在部分物件的鍵會變成選填(Valibot 用 v.optional,JSON Schema 則不列入 required)。

在工具中試用

常見問題

有了 TypeScript 型別,還需要 Zod 嗎?

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

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

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

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

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