Schema 预览工作流：JSON Schema、Zod、TypeScript、GraphQL 与 Protobuf
围绕 API 契约、运行时校验、TypeScript 类型、表单预览、GraphQL SDL 和 Protobuf schema，建立发布前 schema review 流程。
Schema 问题的本质是多个事实来源不一致
后端可能维护 JSON Schema，前端使用 TypeScript，运行时校验写在 Zod，GraphQL 或 Protobuf 又承担另一套契约。只看其中一个文件，很容易漏掉 required、nullable、enum、default 和嵌套结构变化。
支柱文章的目标不是解释每种格式的语法，而是帮助读者建立一条能复用的 schema review 路径：先看类型意图，再看运行时行为，最后看契约和表单呈现。
用 TypeScript 先看字段层级和开发者意图
TypeScript interface 最适合让前端、SDK 和文档读者快速理解字段层级。它能表达可选字段、联合类型和嵌套模型，但不能证明运行时真的会校验。
如果一个字段在 TypeScript 里是可选，在 JSON Schema 里却是 required，就应该在文章里明确标为破坏性风险。
export interface UserProfile {
id: string;
email: string;
role?: "admin" | "viewer";
settings: {
theme: "light" | "dark";
weeklyDigest: boolean;
};
}用 Zod 检查真实输入会在哪里失败
Zod 关注运行时行为：email 校验、默认值、transform、refine、自定义错误消息都在这一层。很多线上问题不是类型写错，而是用户输入到了类型系统看不到的边界。
文章里可以把 Zod 预览作为“从文档到运行时”的桥，提醒读者检查错误消息和默认值是否同步到 API 示例。
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()
})
});用 JSON Schema 和表单预览检查契约是否能被消费
JSON Schema 更适合跨语言共享，也常被用于表单生成、API 文档和校验器。可视化时要重点看 required、nullable、array items、additionalProperties、oneOf/anyOf。
如果 schema 能生成表单，还应该检查字段顺序、描述、枚举文案和非法 payload 的错误反馈。搜索“JSON Schema 表单预览”的用户通常关心这个。
{
"type": "object",
"required": ["id", "email", "settings"],
"properties": {
"email": {"type": "string", "format": "email"},
"role": {"type": "string", "enum": ["admin", "viewer"]},
"settings": {"type": "object"}
}
}GraphQL 和 Protobuf 要特别关注兼容性
GraphQL 里 nullable 到 non-null、删除 enum 值、修改参数都可能影响客户端。Protobuf 里字段编号、reserved、repeated、message 引用和 service request/response 才是 review 重点。
这类文章不要承诺“可视化能证明兼容”，更准确的说法是：可视化能把高风险变更暴露出来，最终仍要结合各自协议的兼容规则。
type Query {
user(id: ID!): User
}
type User {
id: ID!
email: String!
role: Role
}
enum Role { ADMIN VIEWER }Schema review checklist 和内链建议
发布前至少检查 required、nullable、enum、default、array item、additionalProperties、oneOf/anyOf、错误消息和表单字段顺序。再准备一个合法 payload 和一个非法 payload。
内链上建议把 JSON Schema Visualizer、Zod Schema Visualizer、TypeScript Interface Visualizer、JSON Schema Form Preview、GraphQL Schema Visualizer 和 Protobuf Schema Visualizer 都连接到这篇支柱文章。