该技能用于定义或审阅 Zod schema,以及用 Zod 解析不可信数据,面向 Zod v4 约定,核心是把 schema 视为不可信数据边界的、自己所拥有的契约:它定义可接受的线上值,产出可信的领域值,并让非法输入成为显式、有意的结果。
主要能力与用法:
-
契约与信任边界:让 schema 成为线上数据的、可信的、所拥有的契约;在数据成为领域值之前,于其信任边界校验序列化数据,包括已认证的外部载荷。
-
单一来源:保持 schema 及其标准字符串格式作为唯一事实来源,而不是复制类型或自定义格式逻辑;在同一个 z 导入下使用构造器与格式校验器,避免混用导入形式。
-
类型推断:当 transform 或 default 使可接受输入与解析输出不同时,用 z.input 或 z.infer 推断正确一侧,而非手写任一类型。
-
完整协议:在 schema 中表达完整协议契约;标准字符串格式选择 Zod 的顶层校验器,而非用自定义正则重建格式;用匹配的包装器表达缺失与 null 语义,而不是能编译过的任意包装器。
-
默认值与分支:在 schema 中定义具有确切领域含义的默认值,不用默认值把未知或非法输入转为任意兜底;用 z.discriminatedUnion 分派字面量标签的可选分支,而非用 z.union 逐个尝试各标签分支。
-
未知键:当未知键具有契约含义时选择匹配的对象构造器——宽松用 strip、封闭契约用 reject、仅透传不透明数据时保留。
-
失败契约:依据失败契约选择解析 API——中止被违反的不变量,或返回预期的校验分支;从 Zod 的错误中派生预期的校验呈现,而不是丢弃其字段信息。
-
校验规则:单值与单布尔规则用 .refine();多字段或多问题校验移到 .check();多字段关系用 .check() 给出各自可行动的独立 issue,而不是合并为一个 .refine() 错误。
限制与说明:该技能要求先阅读适用于当前任务的参考资料再定义或审阅 schema 与解析代码;文档与实现细节分别来自 Context7 与 DeepWiki。价格、平台、具体代码示例等事实资料暂未提供。