zod

Zod 最佳实践

面向 TypeScript 应用的 Zod 综合模式验证指南。包含 8 个类别中的 43 条规则，并按影响程度排序，以指导自动化重构和代码生成。

适用场景

在以下情况下，请参考这些指南：

• 编写新的 Zod 模式
• 在 parse() 和 safeParse() 之间进行选择
• 使用 z.infer 实现类型推断
• 处理验证错误并向用户提供反馈
• 组合复杂的对象模式
• 使用细化和转换
• 优化打包体积和验证性能
• 审查 Zod 代码的最佳实践

按优先级划分的规则类别

优先级	类别	影响	前缀
1	模式定义	严重	schema-
2	解析与验证	严重	parse-
3	类型推断	高	type-
4	错误处理	高	error-
5	对象模式	中高	object-
6	模式组合	中	compose-
7	细化与转换	中	refine-
8	性能与打包	中低	perf-

快速参考

1. 模式定义（严重）

• schema-use-primitives-correctly - 为每种类型使用正确的基本类型模式
• schema-use-unknown-not-any - 使用 z.unknown() 而非 z.any()，以确保类型安全
• schema-avoid-optional-abuse - 避免过度使用可选字段
• schema-string-validations - 在定义模式时应用字符串验证
• schema-use-enums - 对固定字符串值使用枚举
• schema-coercion-for-form-data - 对表单和查询数据使用强制转换

2. 解析与验证（严重）

• parse-use-safeparse - 对用户输入使用 safeParse()
• parse-async-for-async-refinements - 对异步细化使用 parseAsync
• parse-handle-all-issues - 处理所有验证问题，而不只是第一个
• parse-validate-early - 在系统边界处进行验证
• parse-avoid-double-validation - 避免对同一数据重复验证
• parse-never-trust-json - 切勿信任 JSON.parse 的输出

3. 类型推断（高）

• type-use-z-infer - 使用 z.infer，而非手动定义类型
• type-input-vs-output - 对转换区分 z.input 和 z.infer
• type-export-schemas-and-types - 同时导出模式和推断出的类型
• type-branded-types - 使用品牌类型确保领域安全
• type-enable-strict-mode - 启用 TypeScript 严格模式

4. 错误处理（高）

• error-custom-messages - 提供自定义错误消息
• error-use-flatten - 使用 flatten() 显示表单错误
• error-path-for-nested - 使用 issue.path 定位嵌套错误
• error-i18n - 实现国际化错误消息
• error-avoid-throwing-in-refine - 在 refine 中返回 false，而非抛出异常

5. 对象模式（中高）

• object-strict-vs-strip - 为未知键选择 strict() 或 strip()
• object-partial-for-updates - 对更新模式使用 partial()
• object-pick-omit - 使用 pick() 和 omit() 创建模式变体
• object-extend-for-composition - 使用 extend() 添加字段
• object-optional-vs-nullable - 区分 optional() 和 nullable()
• object-discriminated-unions - 使用可辨识联合进行类型收窄

6. 模式组合（中）

• compose-shared-schemas - 将共享模式提取到可复用模块中
• compose-intersection - 使用 intersection() 组合类型
• compose-lazy-recursive - 对递归模式使用 z.lazy()
• compose-preprocess - 使用 preprocess() 规范化数据
• compose-pipe - 使用 pipe() 进行多阶段验证

7. 细化与转换（中）

• refine-vs-superrefine - 正确选择 refine() 或 superRefine()
• refine-transform-coerce - 区分 transform()、refine() 和 coerce()
• refine-add-path - 为细化错误添加 path
• refine-defaults - 对带默认值的可选字段使用 default()
• refine-catch - 使用 catch() 实现容错解析

8. 性能与包体积（低-中）

• perf-cache-schemas - 缓存 schema 实例
• perf-zod-mini - 在对包体积敏感的应用中使用 Zod Mini
• perf-avoid-dynamic-creation - 避免在热点路径中动态创建 schema
• perf-lazy-loading - 延迟加载大型 schema
• perf-arrays - 优化大型数组的验证

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板
• 各项规则：references/{prefix}-{slug}.md

完整编译文档

如需查看包含所有展开规则的完整指南：AGENTS.md

相关技能

• 如需了解 React Hook Form 集成，请参阅 react-hook-form 技能
• 如需了解 API 客户端生成，请参阅 orval 技能

来源

• Zod 官方文档
• Zod v4 发行说明
• Zod GitHub 仓库
• Zod Mini
• Total TypeScript Zod 教程