zod

Zod 最佳实践

TypeScript 应用中 Zod 的全面模式验证指南。包含 8 个类别共 43 条规则，按影响优先级排序，以指导自动化重构和代码生成。

何时应用

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

• 编写新的 Zod 模式
• 在 parse() 和 safeParse() 之间选择
• 使用 z.infer 实现类型推断
• 处理验证错误以提供用户反馈
• 组合复杂对象模式
• 使用 refinements 和 transforms
• 优化包大小和验证性能
• 审查 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 - 为细化错误添加路径
• refine-defaults - 对带默认值的可选字段使用 default()
• refine-catch - 使用 catch() 进行容错解析

8. 性能与包大小（低中）

• perf-cache-schemas - 缓存模式实例
• perf-zod-mini - 对包大小敏感的应用使用 Zod Mini
• perf-avoid-dynamic-creation - 避免在热路径中动态创建模式
• perf-lazy-loading - 延迟加载大型模式
• 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 教程