2026-06-1614 分鐘閱讀

Schema 預覽工作流：TypeScript、Zod、JSON Schema 与表单預覽

一篇更完整的 Schema 文件教程，覆盖 TypeScript 类型、Zod 執行期校验、JSON Schema 契約、表单預覽和常见不一致案例。

为什么 Schema 文件容易过期

Schema 文件经常漂移，因为不同團隊使用不同事实来源。后端可能维护 JSON Schema，前端写 TypeScript，執行期校验在 Zod，產品和测试更关心表单到底长什么样。

所以这篇文章不应该只介绍某一种格式，而应该展示如何把这些层串起来比對。

Schema 到表单預覽工作流 — 有价值的不是某一种格式，而是从类型、執行期校验、契約到表单預覽的一条链路。

Demo 1：TypeScript 表达开发者意图

TypeScript 对前端和 SDK 开发者最友好，可以快速看出可选欄位、嵌套模型和命名约定。

但 TypeScript 本身不验证執行期输入，所以它更像开发者意图，不应该单独当作 API 契約。

export interface UserProfile {
  id: string;
  email: string;
  role?: "admin" | "viewer";
  settings: {
    theme: "light" | "dark";
    weeklyDigest: boolean;
  };
}

先預覽 interface，可以让读者快速理解欄位層級。

Demo 2：Zod 体现執行期行为

Zod 关注執行期：必填、信箱格式、預設值、转换和錯誤消息都在这里发生。真實使用者输入也是在这一层失敗。

当 Zod 和 TypeScript 不一致时，預覽工具应该帮助你提前发现。

const UserProfileSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(["admin", "viewer"]).default("viewer"),
  settings: z.object({
    theme: z.enum(["light", "dark"]),
    weeklyDigest: z.boolean()
  })
});

Zod 預覽适合檢查預設值、列舉和執行期校验规则。

Demo 3：JSON Schema 用于契約和表单預覽

JSON Schema 更适合跨语言共享，可以用于 API 文件、校验器、生成表单和範例。

表单預覽很重要，因为產品、测试和非前端同学可以直接檢查必填项、列舉和描述，而不用读原始 JSON。

json

{
  "title": "UserProfile",
  "type": "object",
  "required": ["id", "email", "settings"],
  "properties": {
    "email": {"type": "string", "format": "email"},
    "role": {"type": "string", "enum": ["admin", "viewer"]},
    "settings": {"type": "object"}
  }
}

JSON Schema 表单預覽能把契約细节变成可 review 的界面。

常见不一致案例

TypeScript 里是可选欄位，但 JSON Schema 里是 required；Zod 有預設值，但 OpenAPI 範例没写；表单預覽是下拉框，真實 UI 却允许自由输入；文件写了嵌套物件，執行期却没有校验。

这些具体案例会让文章更像经验总结，而不是工具介绍。

Schema review checklist

檢查 required、enum、nullable、default、嵌套物件、陣列 item 类型和錯誤消息。然后至少生成一个表单預覽和一个非法 payload 範例。

如果这是公开 API 的契約变更，建议在 release note 里放一张預覽截图，让 reviewer 能快速扫到变化。