格式化错误

Zod 强调错误报告中的 完整性 和 正确性。在许多情况下，将 $ZodError 转换为更有用的格式是很有帮助的。Zod 提供了一些实用工具来实现这一点。

考虑这个简单的对象模式。

import * as z from "zod";
 
const schema = z.strictObject({
  username: z.string(),
  favoriteNumbers: z.array(z.number()),
});

尝试解析这些无效数据会导致包含三个问题的错误。

const result = schema.safeParse({
  username: 1234,
  favoriteNumbers: [1234, "4567"],
  extraKey: 1234,
});
 
result.error!.issues;
[
  {
    expected: 'string',
    code: 'invalid_type',
    path: [ 'username' ],
    message: 'Invalid input: expected string, received number'
  },
  {
    expected: 'number',
    code: 'invalid_type',
    path: [ 'favoriteNumbers', 1 ],
    message: 'Invalid input: expected number, received string'
  },
  {
    code: 'unrecognized_keys',
    keys: [ 'extraKey' ],
    path: [],
    message: 'Unrecognized key: "extraKey"'
  }
];

`z.treeifyError()`

要将此错误转换（“树形化”）为嵌套对象，请使用 z.treeifyError()。

const tree = z.treeifyError(result.error);
 
// =>
{
  errors: [ 'Unrecognized key: "extraKey"' ],
  properties: {
    username: { errors: [ 'Invalid input: expected string, received number' ] },
    favoriteNumbers: {
      errors: [],
      items: [
        undefined,
        {
          errors: [ 'Invalid input: expected number, received string' ]
        }
      ]
    }
  }
}

结果是一个与模式本身对应的嵌套结构。你可以轻松访问发生在特定路径处的错误。errors 字段包含给定路径的错误消息，特殊属性 properties 和 items 允许你深入遍历该树。

tree.properties?.username?.errors;
// => ["Invalid input: expected string, received number"]
 
tree.properties?.favoriteNumbers?.items?.[1]?.errors;
// => ["Invalid input: expected number, received string"];

访问嵌套属性时，请务必使用可选链操作符（?.）以避免错误。

`z.prettifyError()`

z.prettifyError() 提供了错误的人类可读字符串表示。

const pretty = z.prettifyError(result.error);

它返回以下字符串：

✖ Unrecognized key: "extraKey"
✖ Invalid input: expected string, received number
  → at username
✖ Invalid input: expected number, received string
  → at favoriteNumbers[1]

`z.formatError()`

该方法已被弃用，建议使用 z.treeifyError() 替代。

`z.flattenError()`

虽然 z.treeifyError() 对于遍历可能复杂的嵌套结构很有用，但绝大多数模式是扁平的——仅有一级深度。在这种情况下，使用 z.flattenError() 获取一个干净的、浅层的错误对象。

const flattened = z.flattenError(result.error);
// { errors: string[], properties: { [key: string]: string[] } }
 
{
  formErrors: [ 'Unrecognized key: "extraKey"' ],
  fieldErrors: {
    username: [ 'Invalid input: expected string, received number' ],
    favoriteNumbers: [ 'Invalid input: expected number, received string' ]
  }
}

formErrors 数组包含任何顶层错误（即 path 为空数组）。fieldErrors 对象为模式中的每个字段提供错误数组。

flattened.fieldErrors.username; // => [ 'Invalid input: expected string, received number' ]
flattened.fieldErrors.favoriteNumbers; // => [ 'Invalid input: expected number, received string' ]

z.treeifyError()

z.prettifyError()

z.formatError()

显示文档

z.flattenError()

On this page

`z.treeifyError()`

`z.prettifyError()`

`z.formatError()`

`z.flattenError()`