name: zod description: Zod模式验证最佳实践，用于类型安全、解析和错误处理。此技能应在定义z.object模式、使用z.string验证、safeParse或z.infer时使用。此技能不涵盖React Hook Form集成模式（使用react-hook-form技能）或OpenAPI客户端生成（使用orval技能）。
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- 对异步精炼使用parseAsyncparse-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- 在精炼中返回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 Miniperf-avoid-dynamic-creation- 避免在热路径中动态创建模式perf-lazy-loading- 懒加载大型模式perf-arrays- 优化大型数组验证
如何使用
阅读个别参考文件以获取详细解释和代码示例：
完整编译文档
有关所有规则扩展的完整指南：AGENTS.md
相关技能
- 对于React Hook Form集成，请参见
react-hook-form技能 - 对于API客户端生成，请参见
orval技能