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 能快速扫到变化。