JSON 转 Zod Schema
从 JSON 数据即时生成 Zod 验证 schema,支持嵌套对象、数组、nullable 字段和可选属性。在浏览器中运行。
- 在浏览器中处理
- 工具不会把输入上传到 ZeroTool 服务器
- 免费 · 无需注册
用微信扫描以下二维码即可分享
示例、说明与常见问题 带实际输出的示例、与同类工具的差别,以及常见问题。
输出是什么样子
输出是一段可以直接粘进 .ts 文件的代码:第一行 import { z } from "zod";,中间是 const 名称Schema = …;,最后是 export type 名称 = z.infer<typeof 名称Schema>;。schema 常量没有 export,别的模块要用时自己加上。名称取自「根 Schema 名称」,留空时用 Root。
示例:中文键名的订单
低代码平台或报表导出的 JSON 常用中文键名。根名称填 Order:
{"订单号":"A-1001","收货地址":{"省份":"浙江省","城市":"杭州市"},"商品列表":[{"名称":"龙井茶","数量":2,"单价":128.5},{"名称":"茶具","数量":1,"单价":299,"备注":"礼盒装"}]}
输出:
import { z } from "zod";
const OrderSchema = z.object({
"订单号": z.string(),
"收货地址": z.object({
"省份": z.string(),
"城市": z.string(),
}),
"商品列表": z.array(z.object({
"名称": z.string(),
"数量": z.number().int(),
"单价": z.union([z.number(), z.number().int()]),
"备注": z.string().optional(),
})),
});
export type Order = z.infer<typeof OrderSchema>;
三处值得注意:
- 中文键名一律加引号,这是合法的 JavaScript 对象键。
单价在第一件商品是128.5、第二件是299,生成器把两种数字都列进z.union。这个 union 等价于z.number(),直接改成z.number()更清楚。如果样本里的价格碰巧都是整数,就只会得到z.number().int(),以后遇到128.5会校验失败,所以价格字段要手动检查。备注只在第二件商品里出现,所以加了.optional()。
根名称按 ECMAScript 标识符规则处理,首字母变成大写:中文等各国文字的字母、数字以及 $、_ 都保留,用户 得到 用户Schema;其他字符被去掉、后一个字母变成大写,user profile 得到 UserProfileSchema;不能作为开头的加前缀 T,2fa 得到 T2faSchema。什么都不剩时用 Root。
示例:后端返回的 19 位 ID
很多 Java 后端用 MyBatis-Plus 的 IdType.ASSIGN_ID 生成主键。按 MyBatis-Plus 注解文档,它默认用雪花算法,适用于 Long、Integer、String 类型的主键。主键是 Long 时,接口返回的 JSON 里会是一个很长的数字。根名称填 UserResult:
{"code":200,"msg":"操作成功","data":{"id":1830000000000000001,"userName":"张三","remark":null}}
输出:
import { z } from "zod";
const UserResultSchema = z.object({
code: z.number().int(),
msg: z.string(),
data: z.object({
id: z.number().int(),
userName: z.string(),
remark: z.null(),
}),
});
export type UserResult = z.infer<typeof UserResultSchema>;
1830000000000000001 大于 Number.MAX_SAFE_INTEGER(9007199254740991,见 MDN),JSON.parse 读出来是 1830000000000000000,生成器和你的前端拿到的都是这个已经变了的值。用这份 schema 去校验这份样本,两个版本的结果不同:Zod 3 的 z.number().int() 放行,错误的 ID 一路传下去;Zod 4 的 z.number().int() 只接受安全范围内的整数,报 Too big: expected int to be <9007199254740991。两种结果都说明数字类型装不下这个 ID,应让后端把它输出成字符串,schema 改为 z.string().regex(/^\d+$/)。
remark 样本里是 null,生成 z.null(),只接受 null。按接口文档改成 z.string().nullable()。
生成后怎么改
| 生成结果 | 问题 | 改为(Zod 4) |
|---|---|---|
email: z.string() | 任意字符串都能通过 | z.email()(Zod 3:z.string().email()) |
数量: z.number().int() | 只有一定是整数时才对,10.5 会报 Invalid input: expected int, received number | 价格类字段用 z.number(),再加 .min(0) |
remark: z.null() | 只有 null 能通过 | z.string().nullable() |
status: z.string() | 任意字符串都能通过 | z.enum(["active", "inactive"]) |
| 样本里出现过的字段 | 一律必填,即使接口有时不返回 | 加 .optional() |
失败就应该停止运行的地方(如启动时读配置)用 .parse(),它会抛出 ZodError;接口响应和用户输入用 .safeParse(),它返回 { success: false, error },由你自己处理错误。
限制
- 类型只来自一份样本。 空数组生成
z.array(z.unknown()),空对象生成z.record(z.string(), z.unknown())。 null生成z.null()。 不会自动加.nullable()。在对象数组里,某个键在第一项是null、第二项是字符串时,生成z.union([z.null(), z.string()])。- 混合数组生成 union。
[{"a": 1}, 2]这样的数组,不论在根上还是在对象内部,都生成z.array(z.union([z.number().int(), z.object({ a: z.number().int() })]))。同一数组里的对象合并成一个z.object,所以 union 里只有一个对象成员。 - 同一个键既有整数又有小数时生成 union。
z.union([z.number(), z.number().int()])可以直接改成z.number()。 - 大整数。 输入用
JSON.parse读取,大于 9007199254740991 的整数在生成 schema 之前就已经变了。 - 没有字符串格式与范围。 邮箱、URL、日期、UUID 都是
z.string()。 - 嵌套极深时可能超出浏览器的调用栈。 这时状态栏显示错误,之前的 schema 被清空,「复制」按钮停用。
- 输入必须是合法 JSON。 无效时输出被清空、「复制」按钮停用,状态栏给出出错的行、列和可能的原因,行列按你输入的原文计算。中文输入法带进来的全角冒号会被指出来:
{"订单号":"A-1001"}显示JSON 格式错误:第 1 行第 7 列,全角字符 :;JSON 的标点和空格必须是半角。
FAQ
什么是 Zod?
Zod 是一个 TypeScript 优先的 schema 声明和验证库,让你定义数据结构并在运行时进行验证。广泛应用于 API 响应验证、表单验证和配置解析。
生成器如何推断类型?
生成器检查每个 JSON 值:字符串 → z.string(),布尔 → z.boolean(),整数 → z.number().int(),小数 → z.number(),null → z.null(),数组 → z.array(),对象 → z.object()。对于对象数组,只在部分元素中出现的键会加 .optional(),不同元素里类型不同的键会生成 z.union。
什么是严格模式?
勾选「严格模式(不允许多余字段)」后,每个 z.object() 后都会追加 .strict(),嵌套对象也一样。Zod 会拒绝包含 schema 中未定义字段的输入对象。不勾选时,多余字段会从解析结果里被悄悄去掉(Zod 默认行为)。
生成的代码能用于 Zod 3 和 Zod 4 吗?
能。生成器只用 z.object、z.array、z.union、z.record、z.string、z.number().int()、z.boolean、z.null、z.unknown、.optional() 和 .strict(),两个版本都有。本页示例在 TypeScript 严格模式下分别对 Zod 3 和 Zod 4 API(zod/v4)编译通过。有一处差别:Zod 4 的 z.number().int() 还会拒绝超出安全整数范围(大于 9007199254740991)的整数。
生成的 schema 可以直接用于生产吗?
生成的 schema 适合当初稿,用到生产前按业务补上约束,例如给字符串和数字加 .min()/.max(),把可能为 null 的字段改成 .nullable().optional(),或把嵌套的 schema 拆成单独命名的常量。
我的 JSON 数据会发送到服务器吗?
不会。页面在浏览器里根据你的 JSON 生成 schema,不把 JSON 发送到任何地方,也不保存到浏览器存储。页面的统计只在你改完输入、焦点离开输入框后,或点击「生成 Zod Schema」「示例」时记录一次使用事件(工具名和动作 generate),不包含 JSON 或生成的代码。