用途:为 TypeScript 应用中的 Zod 模式校验提供最佳实践指南,包含 8 个类别共 43 条规则,按影响优先级排列,用于指导自动重构与代码生成。
适用时机:编写新 Zod 模式;在 parse() 与 safeParse() 之间选择;用 z.infer 实现类型推断;处理校验错误以反馈用户;组合复杂对象模式;使用 refine 与 transform;优化打包体积与校验性能;审查 Zod 代码。
主要能力(按优先级):模式定义(CRITICAL):正确使用原始类型、用 z.unknown() 而非 any、避免滥用 optional、在定义处做字符串校验、用枚举处理固定字符串值、对表单与查询数据使用强制转换。解析与校验(CRITICAL):用户输入用 safeParse()、异步 refine 用 parseAsync、处理全部问题而非仅首个、在系统边界尽早校验、避免重复校验、不信任 JSON.parse 输出。类型推断(HIGH):用 z.infer 替代手写类型、区分 z.input 与 z.infer、同时导出模式与推断类型、使用品牌类型、启用 TS 严格模式。错误处理(HIGH):自定义错误消息、用 flatten() 展示表单错误、用 issue.path 定位嵌套错误、实现国际化消息、refine 中返回 false 而非抛出。对象模式(MEDIUM-HIGH):选择 strict() 与 strip()、用 partial() 做更新模式、用 pick()/omit() 生成变体、用 extend() 组合、区分 optional() 与 nullable()、可辨识联合做类型收窄。模式组合(MEDIUM):抽取共享模式、intersection() 组合、z.lazy() 递归、preprocess() 归一化、pipe() 多阶段校验。精炼与转换(MEDIUM):正确选择 refine() 与 superRefine()、区分 transform()/refine()/coerce()、为精炼错误添加 path、用 default() 设默认值、用 catch() 容错解析。性能与打包(LOW-MEDIUM):缓存模式实例、对体积敏感应用用 Zod Mini、避免热路径动态创建模式、懒加载大型模式、优化大数组校验。
使用方式:阅读各参考文件获取详细说明与代码示例;分类定义参见 section definitions,规则模板见 rule template,单条规则位于 references/{prefix}-{slug}.md;完整指南见 AGENTS.md。React Hook Form 集成参见 react-hook-form 技能,API 客户端生成参见 orval 技能。
来源:Zod 官方文档、Zod v4 发布说明、Zod GitHub 仓库、Zod Mini、Total TypeScript Zod 教程。
限制:资料未提供安装命令、价格或具体平台兼容性信息,暂未提供。