zod

Zod 最佳實務

在 TypeScript 應用程式中使用 Zod 的完整結構驗證指南。包含 8 個類別共 43 條規則，按影響程度排序，以引導自動重構與程式碼產生。

適用時機

請在以下情況參考這些指南：

• 撰寫新的 Zod 結構
• 在 parse() 與 safeParse() 之間選擇
• 使用 z.infer 實作型別推論
• 處理驗證錯誤以提供使用者回饋
• 組合複雜的物件結構
• 使用 refinements 與 transforms
• 最佳化 bundle 大小與驗證效能
• 審查 Zod 程式碼以符合最佳實務

規則類別（依優先順序）

優先順序	類別	影響程度	前綴
1	結構定義	關鍵	schema-
2	解析與驗證	關鍵	parse-
3	型別推論	高	type-
4	錯誤處理	高	error-
5	物件結構	中高	object-
6	結構組合	中	compose-
7	Refinements 與 Transforms	中	refine-
8	效能與 Bundle	低中	perf-

快速參考

1. 結構定義（關鍵）

• schema-use-primitives-correctly - 為每種型別使用正確的基本結構
• schema-use-unknown-not-any - 使用 z.unknown() 而非 z.any() 以確保型別安全
• schema-avoid-optional-abuse - 避免過度使用 optional 欄位
• schema-string-validations - 在結構定義時套用字串驗證
• schema-use-enums - 對固定字串值使用列舉
• schema-coercion-for-form-data - 對表單與查詢資料使用強制轉型

2. 解析與驗證（關鍵）

• parse-use-safeparse - 對使用者輸入使用 safeParse()
• parse-async-for-async-refinements - 對非同步 refinements 使用 parseAsync
• parse-handle-all-issues - 處理所有驗證問題，而非僅第一個
• parse-validate-early - 在系統邊界進行驗證
• parse-avoid-double-validation - 避免對相同資料驗證兩次
• parse-never-trust-json - 絕不信任 JSON.parse 的輸出

3. 型別推論（高）

• type-use-z-infer - 使用 z.infer 而非手動定義型別
• type-input-vs-output - 區分 z.input 與 z.infer（用於 transforms）
• type-export-schemas-and-types - 同時匯出結構與推論型別
• type-branded-types - 使用 branded types 確保領域安全
• type-enable-strict-mode - 啟用 TypeScript 嚴格模式

4. 錯誤處理（高）

• error-custom-messages - 提供自訂錯誤訊息
• error-use-flatten - 使用 flatten() 顯示表單錯誤
• error-path-for-nested - 使用 issue.path 定位巢狀錯誤
• error-i18n - 實作國際化錯誤訊息
• error-avoid-throwing-in-refine - 在 refine 中回傳 false 而非拋出例外

5. 物件結構（中高）

• object-strict-vs-strip - 針對未知鍵選擇 strict() 或 strip()
• object-partial-for-updates - 對更新結構使用 partial()
• object-pick-omit - 使用 pick() 與 omit() 產生結構變體
• object-extend-for-composition - 使用 extend() 新增欄位
• object-optional-vs-nullable - 區分 optional() 與 nullable()
• object-discriminated-unions - 使用 discriminated unions 進行型別縮小

6. 結構組合（中）

• compose-shared-schemas - 將共用結構抽取為可重複使用的模組
• compose-intersection - 使用 intersection() 進行型別組合
• compose-lazy-recursive - 使用 z.lazy() 處理遞迴結構
• compose-preprocess - 使用 preprocess() 進行資料正規化
• compose-pipe - 使用 pipe() 進行多階段驗證

7. Refinements 與 Transforms（中）

• refine-vs-superrefine - 正確選擇 refine() 或 superRefine()
• refine-transform-coerce - 區分 transform()、refine() 與 coerce()
• refine-add-path - 在 refinement 錯誤中加入路徑
• refine-defaults - 對有預設值的 optional 欄位使用 default()
• refine-catch - 使用 catch() 進行容錯解析

8. 效能與 Bundle（低中）

• perf-cache-schemas - 快取結構實例
• perf-zod-mini - 對 bundle 大小敏感的應用程式使用 Zod Mini
• perf-avoid-dynamic-creation - 避免在熱路徑中動態建立結構
• perf-lazy-loading - 延遲載入大型結構
• perf-arrays - 最佳化大型陣列驗證

使用方式

閱讀個別參考檔案以取得詳細說明與程式碼範例：

• 章節定義 - 類別結構與影響程度
• 規則範本 - 新增規則的範本
• 個別規則：references/{prefix}-{slug}.md

完整彙編文件

完整指南（含所有規則展開）：AGENTS.md

相關技能

• 如需 React Hook Form 整合，請參閱 react-hook-form 技能
• 如需 API 客戶端產生，請參閱 orval 技能

來源

• Zod 官方文件
• Zod v4 發行說明
• Zod GitHub 儲存庫
• Zod Mini
• Total TypeScript Zod 教學