错误处理

1. 错误处理概述

Zod 的错误处理系统旨在提供有关验证失败的详细、结构化信息。当验证失败时，Zod 会生成一个 ZodError 实例，其中包含一个或多个 ZodIssue 对象，描述了错误发生的原因和位置。这些错误可以通过各种方式进行自定义、格式化和处理，以改善用户体验。

来源

2. 核心错误组件

2.1 ZodError 类

ZodError 类是 Zod 错误处理系统的基础。它扩展了 JavaScript 原生的 Error 类，并包含一系列验证问题。

关键属性和方法

issues: 一个 ZodIssue 对象数组，详细说明了验证期间失败的原因
format(): 将错误转换为反映数据形状的嵌套结构
flatten(): 创建一个按字段分组的扁平结构
addIssue()/addIssues(): 用于向错误添加新问题的方法

来源

2.2 ZodIssue 结构

ZodIssue 是一个可辨识联合类型，代表不同种类的验证失败。每个问题都包含通用字段和类型特定的信息。

所有 ZodIssue 中的通用字段

字段	类型	描述
`code`	`ZodIssueCode`	标识验证失败的类型
`path`	`(string \| number)[]`	无效数据的路径（例如，`["user", "email"]`）
`message`	`字符串`	人类可读的错误消息
`fatal?`	`布尔值`	错误是否致命且应中止验证

不同的问题类型根据其代码包含额外的字段。例如

invalid_type 问题包括 expected 和 received 类型
too_small 问题包括 minimum、inclusive 和 type 字段
custom 问题可以包含自定义 params

来源

2.3 ZodIssueCode 枚举

ZodIssueCode 枚举标识了不同类型的验证失败

来源

3. 错误生成过程

当验证失败时，Zod 会通过结构化过程创建并收集问题

此过程中的关键函数是

makeIssue: 通过应用错误映射创建带有适当消息的 ZodIssue
addIssueToContext: 将问题添加到当前验证上下文

来源

4. 自定义错误消息

Zod 提供了一个灵活的系统，通过错误映射来自定义错误消息。

4.1 错误映射概念

错误映射是一个具有以下签名的函数

它接收有关问题和上下文的信息，然后返回自定义消息。

4.2 错误映射优先级链

Zod 按照特定的优先级顺序应用错误映射，链中优先级较高的映射会覆盖优先级较低的映射

来源

4.3 设置错误映射

有几种方法可以设置错误映射

全局错误映射:
模式绑定错误映射:
上下文错误映射:

来源

5. 错误处理

5.1 捕获和处理 ZodErrors

您可以在 try/catch 块中捕获和处理验证错误

或者，使用 safeParse 来避免 try/catch

来源

ERROR_HANDLING.md89-149

5.2 格式化错误以供显示

Zod 提供了两种主要方法来格式化错误以供显示

5.2.1 使用 `format()` 进行嵌套格式化

format() 方法返回一个反映数据形状的嵌套结构

format() 方法还可以接受一个自定义映射函数来转换问题。

来源

5.2.2 使用 `flatten()` 进行扁平格式化

flatten() 方法生成一个更简单的结构，非常适合表单验证

这对于在 UI 库中将错误映射到表单字段特别有用。

来源

5.3 推断错误类型

您可以推断格式化错误的类型签名以确保类型安全

这在前端应用程序中使用 TypeScript 时特别有用。

来源

当使用 refine() 或 superRefine() 进行自定义验证时，您可以指定自定义错误路径和参数

您还可以动态生成错误元数据

来源

总结

Zod 的错误处理系统提供了详细、结构化的验证错误，并具有灵活的自定义选项。其核心组件（ZodError、ZodIssue、错误映射）协同工作，帮助开发者创建具有用户友好错误消息的健壮验证。通过使用格式化方法（format() 和 flatten()），您可以以适合应用程序 UI 的方式呈现这些错误。

对于更复杂的场景，可以考虑探索自定义错误映射和细化，以根据您的特定需求定制验证体验。