基本用法

本页面将带你了解创建 schema、解析数据以及使用推断类型的基础知识。有关 Zod schema API 的完整文档，请参阅定义 schema

定义 schema

在做其他操作之前，你需要先定义一个 schema。为了本指南的目的，我们将使用一个简单的对象 schema。

import * as z from "zod"; 
 
const Player = z.object({ 
  username: z.string(),
  xp: z.number()
});

解析数据

对于任何 Zod schema，使用 .parse 方法验证输入。如果输入有效，Zod 会返回输入的强类型深拷贝。

Player.parse({ username: "billie", xp: 100 }); 
// => 返回 { username: "billie", xp: 100 }

注意 — 如果您的模式使用某些异步 API，如 async 细化或转换，您需要使用 .parseAsync() 方法。

await Player.parseAsync({ username: "billie", xp: 100 });

处理错误

当验证失败时，.parse() 方法会抛出一个 ZodError 实例，其中包含关于验证问题的详细信息。

try {
  Player.parse({ username: 42, xp: "100" });
} catch(error){
  if(error instanceof z.ZodError){
    error.issues; 
    /* [
      {
        expected: 'string',
        code: 'invalid_type',
        path: [ 'username' ],
        message: 'Invalid input: expected string'
      },
      {
        expected: 'number',
        code: 'invalid_type',
        path: [ 'xp' ],
        message: 'Invalid input: expected number'
      }
    ] */
  }
}

为了避免使用 try/catch，你可以使用 .safeParse() 方法获取一个普通的结果对象，该对象包含成功解析的数据或一个 ZodError。该结果类型是一个区分联合类型，因此你可以方便地处理两种情况。

const result = Player.safeParse({ username: 42, xp: "100" });
if (!result.success) {
  result.error;   // ZodError 实例
} else {
  result.data;    // { username: string; xp: number }
}

注意 — 如果您的模式使用某些异步 API，如 async 细化或转换，您需要使用 .safeParseAsync() 方法。

await schema.safeParseAsync("hello");

当你只需要知道某个输入是否可接受时，请使用顶层的 z.validate() 函数。它返回一个布尔值，从不构建错误，并充当 schema 输入类型的类型守卫。对于无效输入，其速度比 .safeParse().success 快至 16 倍。

z.validate(Player, { username: "billie", xp: 100 }); // true
z.validate(Player, { username: 42, xp: "100" });     // false

对于包含异步细化或转换的 schema，请使用 z.validateAsync()。对于已编译的 schema，z.validate() 会直接通过编译后的快速路径返回结果。

推断类型

Zod 会从你的 schema 定义中推断出静态类型。你可以使用 z.infer<> 工具提取该类型，并按需使用。

const Player = z.object({ 
  username: z.string(),
  xp: z.number()
});
 
// 提取推断类型
type Player = z.infer<typeof Player>;
 
// 在代码中使用该类型
const player: Player = { username: "billie", xp: 100 };

在某些情况下，schema 的输入和输出类型可能不一致。例如，.transform() API 可以将输入类型转换为另一种类型。在这种情况下，你可以独立提取输入和输出类型：

const mySchema = z.string().transform((val) => val.length);
 
type MySchemaIn = z.input<typeof mySchema>;
// => string
 
type MySchemaOut = z.output<typeof mySchema>; // 等同于 z.infer<typeof mySchema>
// number

既然已经掌握了基础内容，接下来让我们深入 Schema API。

定义 schema

解析数据

处理错误

推断类型

On this page