JSON 轉 TypeScript 型別指南

為什麼需要 JSON 轉 TypeScript 型別

在前後端協作中，API 回應通常是 JSON 格式。手動編寫 TypeScript 介面既耗時又容易出錯，特別是當介面欄位多、巢狀深時。自動產生型別定義可以：

• 減少手寫介面的工作量
• 避免欄位名拼寫錯誤
• 保持前後端型別一致
• 加速程式碼補全和重構

基本轉換規則

簡單物件

{
  "id": 1,
  "name": "張三",
  "active": true
}

產生結果：

interface RootObject {
  id: number;
  name: string;
  active: boolean;
}

型別對應規則

JSON 值	TypeScript 型別
"hello"	string
42	number
3.14	number
true / false	boolean
null	null
[1, 2, 3]	number[]
{"a": 1}	巢狀介面

使用 JSON→TypeScript工具

步驟一：取得 JSON 資料

從瀏覽器開發者工具的 Network 面板複製 API 回應，或直接貼上已有的 JSON 資料。

步驟二：開啟工具

進入 JSON→TypeScript工具，將 JSON 貼到輸入區域。

步驟三：設定產生選項

• 根介面名稱：預設 RootObject，建議改為語義化名稱（如 UserInfo）
• 匯出修飾詞：選擇 interface 或 type
• 可選欄位：值為 null 的欄位是否標記為可選（?）
• 唯讀修飾詞：是否為所有欄位新增 readonly

步驟四：產生並複製

點擊產生按鈕，TypeScript 型別定義即刻輸出，一鍵複製到剪貼簿。

處理巢狀物件

深層巢狀的 JSON 會自動拆分為多個介面：

{
  "user": {
    "profile": {
      "avatar": "url",
      "bio": "text"
    }
  }
}

產生：

interface Profile {
  avatar: string;
  bio: string;
}

interface User {
  profile: Profile;
}

interface RootObject {
  user: User;
}

建議將產生的介面拆分到獨立檔案中，按模組組織。

處理聯合型別

當陣列中包含不同型別的元素時：

{
  "items": ["text", 42, true]
}

工具會產生聯合型別：

interface RootObject {
  items: (string | number | boolean)[];
}

處理可選欄位

API 回應中某些欄位可能不存在，常見處理方式：

• 欄位值為 null 時標記為可選：bio?: string | null
• 欄位缺失時標記為可選：bio?: string
• 在工具中勾選「null 欄位標記為可選」即可自動處理

實戰：從真實 API 產生型別

1. 開啟瀏覽器開發者工具 → Network 面板
2. 找到目標 API 請求，右鍵 → Copy Response
3. 貼到 JSON→TypeScript工具
4. 設定根介面名稱（如 ApiResponse）
5. 產生後複製到專案的 types/ 目錄

常見問題

問題	原因	解決方法
型別過於具體	單條資料推斷型別	補充多條樣本資料
巢狀層級太深	JSON 結構複雜	手動合併部分介面
陣列元素型別不一致	混合型別陣列	使用聯合型別或泛型
日期變成 string	JSON 無日期型別	手動改為 Date 型別

進階技巧

1. 用 JSON格式化 先整理 JSON 再產生型別
2. 同樣方法可用 JSON→Go工具 產生 Go 結構體
3. 產生的介面建議搭配 Zod 做執行時校驗
4. 大型專案推薦用 openapi-typescript 從 Swagger 產生

總結

從 JSON 自動產生 TypeScript 型別是提升開發效率的利器。JSON→TypeScript工具 讓你在幾秒內完成型別定義，避免手動編寫的繁瑣和錯誤。結合本文的巢狀處理、可選欄位等技巧，可以應對各種複雜場景。