指南

從 JSON 產生 TypeScript、Zod 與 Pydantic v2 型別安全模型

將 API JSON 範例在本機轉成嚴謹的 TypeScript 介面、Zod 執行期驗證器與 Python Pydantic v2 模型,支援可選欄位與別名推斷。

2 分鐘閱讀

快速解答: 從真實 API JSON 回應直接推斷產生 `TypeScript` 介面、執行階段 `Zod` 驗證器與 Python `Pydantic v2` 模型,可在編譯與執行階段拦截欄位遺漏與型別偏差。TxtTo 在瀏覽器本地推導聯合型別與巢狀物件,內部介面範例絕不外洩。

為何在 API 邊界僅仰賴編譯期型別仍不夠保險

TypeScript 介面在編譯之後便會完全消失。如果外部 Webhook 突然更改鍵名或意外回傳 `null`,靜態介面在執行期無法察覺任何異常,直到程式當場拋出錯誤。

將靜態 TypeScript 模型與執行期驗證器(JS/TS 使用 Zod,Python 使用 Pydantic v2)搭配運作,才能確保端到端的資料酬載安全。

在 TypeScript 中推斷可選鍵與聯集型別

真實的 API 陣列極少在第 0 筆資料就帶齊所有可選屬性。「JSON 轉 TypeScript」會檢查陣列裡的每一筆元素,合併所有欄位並自動替部分缺失的鍵名加上 `?`。

ts
export interface EventItem {
  id: string;
  retries?: number;
  error: string | null;
}

從 JSON 產生 TypeScript 介面

透過 Zod 同時兼顧執行期驗證與 z.infer 型別

「JSON 轉 Zod」省去重複維護介面與驗證規則的麻煩,直接輸出巢狀 `z.object(...)` 驗證器與 `export type RootSchema = z.infer<typeof rootSchema>`,讓執行期檢查與靜態型別始終同步。

產生 Zod 驗證 Schema

產生支援 Field 別名的 Python Pydantic v2 BaseModel

JavaScript API 慣用 `camelCase`,而符合 PEP 8 的 Python 偏好 `snake_case`。「JSON 轉 Pydantic」會整齊提升巢狀模型、產生 `Optional[...]` 提示並自動加上 `Field(alias="camelKey")`。

python
class RootModel(BaseModel):
    user_id: str = Field(alias="userId")
    is_active: bool = Field(alias="isActive")

在本機產生 Pydantic v2 模型

參考資料

常見問題

當 JSON 鍵名包含短橫線或 Python 保留字時會怎麼處理?

屬性名稱會自動安全轉義——TypeScript 會替無效識別符加上引號,而 Pydantic 會對應為合法 snake_case 屬性並搭配 Field(alias=...)。

產生的 Zod Schema 應該啟用嚴格物件模式嗎?

驗證嚴謹的內部合約測試時建議開啟「嚴格物件」;介接經常新增無害額外欄位的第三方 API 時保持關閉較為彈性。

可以先整理或修復凌亂的 JSON 再產生程式碼 Schema 嗎?

可以。先透過「JSON 格式化」移除尾隨逗號並檢視樹狀結構,接著點擊「接續使用 JSON 轉 TypeScript」即可。

相關格式

相關方案比較

相關指南