JSON 轉 TypeScript

相關推薦

關於 JSON 轉 TypeScript：把 JSON 資料自動變成 TS 型別

適用場景

• 前端開發時把 REST API 或 GraphQL 回傳的 JSON 響應快速轉為 TS interface，避免手寫型別定義。
• React/Vue/Angular 專案的 Props、State、組件參數需要型別宣告時，從樣本 JSON 幾秒生成。
• 全端 TypeScript 專案中，前後端共享型別定義，後端 mock JSON 即可作為前端 type source of truth。
• 對接第三方 API 時（快遞、天氣、支付等）快速生成對應的 TypeScript 介面，免去查閱文件。
• 從 mock 資料、測試 fixture、JSON 設定檔反推型別定義，用於加強型別安全和 IDE 智慧提示。
• 資料庫 ORM 匯出的 JSON Schema 轉換為 TypeScript interface，整合到 Node.js 後端 DTO 定義。
• 學習 TypeScript 時把已有 JSON 轉為 interface 範例，理解嵌套型別、聯合型別、可選欄位的寫法。
• 程式碼重構時把散落的 JS object literal 轉為正式 interface，提升程式碼可讀性和型別安全。

使用方法

1. 在左側輸入框貼上 JSON 內容，或點擊「上傳」按鈕選擇 .json/.txt 檔案，或點擊「範例」載入內建樣本。
2. 點擊工具列右側的 interface 名稱按鈕（或齒輪圖示），自訂根 interface 名稱（預設 Root）、開啟可選欄位/唯讀欄位。
3. 工具會自動轉換（輸入後 400ms 防抖）；在右側查看生成的 TypeScript interface 程式碼，CodeMirror 高亮便於閱讀。
4. 選擇縮排風格（2 空格或 4 空格），調整工具列左側/右側面板寬度以獲得最佳檢視體驗。
5. 點擊「複製」將 TS 程式碼複製到剪貼簿，或點擊「下載」儲存為 `${interfaceName}.ts` 檔案（如 User.ts）。
6. 將程式碼貼到專案 `types/` 目錄或 `src/types/` 目錄中，按需 import 使用。

功能特點

• 智慧型別推斷：自動識別 null、boolean、number、string、array、object 等 TypeScript 型別，對應為原生 TS 語法。
• 嵌套物件自動展開：為嵌套物件自動建立獨立子 interface（如 RootAddress），保持型別層級清晰、避免冗餘。
• 陣列型別智慧處理：元素型別一致生成 `T[]`，混合型別生成聯合陣列 `(A | B)[]`，空陣列兜底為 `any[]`。
• 可選欄位標記：開啟後自動偵測 null/undefined 欄位，加入 `?` 修飾符，生成符合 TypeScript strict 模式的程式碼。
• 唯讀欄位支援：開啟後為所有欄位加入 `readonly` 修飾符，適合不可變狀態、設定、DTO 等場景。
• interface 名稱自訂：根 interface 名稱可設定（預設 Root），下載檔名以該名稱命名（如 User.ts）。
• 2/4 空格縮排可選：工具列一鍵切換 2 空格（ESLint 預設）和 4 空格縮排風格。
• 即時自動轉換：輸入 JSON 後 400ms 防抖自動轉換，無需點擊按鈕；支援貼上、檔案上傳、範例三種輸入方式。
• JSON 錯誤自修復：內建 tryFixJSON 修復函式，自動處理尾隨逗號、單引號、缺引號等常見語法錯誤。
• TypeScript 程式碼高亮：右側輸出使用 CodeMirror + JavaScript (TypeScript) 高亮，可讀性強。
• 複製與下載：一鍵複製到剪貼簿，或下載為標準 .ts 檔案直接用於前端專案。
• 純瀏覽器本地處理：所有 JSON 解析、型別推斷、interface 生成都在瀏覽器 JavaScript 中完成，原始資料不上傳。

常見問題

故障排查

術語表

JSON（JavaScript Object Notation）

輕量級資料交換格式，基於 JavaScript 物件語法但獨立於程式語言。支援物件 ({}), 陣列 ([]), 字串, 數字, 布林, null 六種基本型別。廣泛用於 REST API、前後端資料傳輸、設定檔、記錄檔等場景。

TypeScript

由 Microsoft 開發的 JavaScript 超集，為 JavaScript 添加了靜態型別定義、介面、泛型等特性。TypeScript 程式碼會被編譯為純 JavaScript 後執行於瀏覽器或 Node.js。是 React、Vue、Angular 等現代前端專案的首選語言。

interface（介面）

TypeScript 中描述物件型別的關鍵字，語法為 `interface Name { prop: type; }`。支援宣告合併（同名 interface 自動合併）、implements（類別實作介面）、extends（介面繼承）。是 TypeScript 描述物件形狀的主要方式。

type 別名

TypeScript 中給型別起別名的關鍵字，語法為 `type Name = ...`。可用於定義聯合型別 (`A | B`)、交叉型別 (`A & B`)、函式型別等。比 interface 更靈活但不支援宣告合併。本工具統一使用 interface 而非 type。

型別推斷（Type Inference）

本工具根據 JSON value 的 typeof 和具體形式自動決定對應 TS 型別的過程。例如 typeof string 對應為 string，Array.isArray() 命中時按陣列處理，typeof object 命中時生成獨立子 interface。

可選欄位（?）

TypeScript 中表示欄位可缺省的修飾符。`name?: string` 表示 name 欄位可不存在（值為 undefined）。開啟本工具的「可選欄位」選項後，值為 null 或 undefined 的欄位會自動加入 `?`。

唯讀欄位（readonly）

TypeScript 中表示欄位不可變的修飾符。`readonly id: number` 表示 id 欄位在物件建立後不能被重新賦值。開啟本工具的「唯讀欄位」選項後，所有欄位會自動加入 `readonly`。

聯合型別（Union Type）

TypeScript 中表示值可以是多種型別之一的語法，寫作 `A | B`。本工具在陣列元素型別不一致時使用，如 `(string | number)[]` 表示陣列元素可能是 string 或 number。

陣列型別（Array Type）

TypeScript 中表示陣列的語法，有兩種形式：泛型形式 `Array<T>` 和簡寫形式 `T[]`。本工具統一使用簡寫形式。本工具有三種陣列型別生成模式：一致型別 `T[]`、混合型別 `(A | B)[]`、空陣列 `any[]`。

嵌套介面（Nested Interface）

在 interface 中引用其他 interface 形成型別層級。本工具為每個嵌套物件生成獨立子 interface，主 interface 透過屬性名引用。如 Root 引用 RootAddress，RootAddress 可以獨立被其他型別引用。

TypeScript strict 模式

TypeScript 編譯器的嚴格模式，包含 noImplicitAny、strictNullChecks、strictFunctionTypes 等多個子選項。開啟 strictNullChecks 後，null 和 undefined 是獨立型別，不能賦給其他型別變數。本工具生成的可選欄位與 strict 模式完全相容。

DTO (Data Transfer Object)

資料傳輸物件，用於在不同層（如 API 與 Service 層）之間傳遞資料。在 TypeScript 專案中通常用 interface 描述，配合 readonly 強調不可變性。本工具是生成 DTO 型別定義的常用工具。

宣告合併（Declaration Merging）

TypeScript interface 的特性：同名 interface 會自動合併屬性。常用於擴展第三方庫的型別定義。本工具生成的 interface 支援與專案中其他同名 interface 合併，便於漸進式型別擴展。

tsconfig.json

TypeScript 專案的設定檔，位於專案根目錄。包含 compilerOptions（target、module、strict 等）、include、exclude 等設定。本工具生成的 .ts 檔案可以放入任何標準 tsconfig 專案中使用。

tryFixJSON

本工具內建的 JSON 修復函式，會自動處理尾隨逗號、單引號代替雙引號、缺引號的 key、註解等常見 JSON 語法錯誤。在 JSON.parse 失敗時自動呼叫，修復成功後會通知使用者並繼續轉換。

JSON 型別到 TypeScript 型別的對應規則

本工具的 getTsType 函式根據 JSON value 的形式推斷 TypeScript 型別的完整規則：

interface vs type 別名對比

本工具選擇生成 interface 而非 type 別名的原因，以及兩者在 TypeScript 專案中的差異：

可選欄位與唯讀欄位的生成規則

本工具的兩個開關選項對生成程式碼的影響和最佳使用場景：

Privacy & Security

本 JSON 轉 TypeScript 工具所有操作完全在你的瀏覽器本地完成：JSON 解析、型別推斷、interface 生成全部透過瀏覽器 JavaScript 在用戶端執行，不會透過網路向任何伺服器傳送 JSON 內容、上傳的檔案或生成的程式碼。檔案上傳使用瀏覽器原生 FileReader API 直接讀取到記憶體，不經過任何中介服務。不使用 Cookie 追蹤，不收集任何使用者輸入或使用資料。關閉或重新整理頁面後，所有輸入和輸出內容自動從記憶體清除。適合處理含 API 金鑰、token、敏感業務資料的 JSON。

Authoritative References

• TypeScriptTypeScript interface 官方文件
• TypeScriptTypeScript 入門手冊
• MDNJSON 規範 - MDN Web Docs
• TypeScriptTypeScript Playground 線上試用
• TypeScripttsconfig.json 設定參考
• ZodZod - TypeScript 優先的 schema 驗證函式庫