Zod 从 0 到 15 个真实场景讲透 TypeScript 数据验证【免费下载链接】zodTypeScript-first schema validation with static type inference项目地址: https://gitcode.com/GitHub_Trending/zo/zod上周凌晨一个中台接口被上游推来的一条脏数据打崩了age字段传回了字符串thirty下一行代码.toFixed()直接抛错502 连响二十分钟。事后复盘只有一句结论——接口入口没有做数据验证。Zod 就是为这一刻而生的 TypeScript 优先模式库你用z.object()描述一次数据结构它既能在运行时拦截脏数据又能让 TypeScript 把类型自动推断出来。一份 schema两件事一次办完。快速上手5 行代码跑起来装包之后你只需要认识两个方法parse通过就返回数据不通过直接抛错safeParse不抛错返回{ success, data, error }供你自行处理。import { z } from zod; const Login z.object({ email: z.string().email(), password: z.string().min(8), }); const res Login.safeParse({ email: ab.com, password: 123 }); console.log(res.success); // false8 位密码这条没过关到这里你已经完成了第一次验证。下面解释一下为什么它值得用。先分清编译期类型 ≠ 运行时验证新人最容易踩的认知坑TS 的类型只活在编辑器里。type Age number; function f(age: Age) { age.toFixed(1); // 看起来稳如老狗 } f(thirty as unknown as Age); // 运行时照样炸编译期类型是一张登机牌只证明你应该是人但机场安检门才是真的会拦你的东西。Zod 就是那扇安检门parse在运行时把每一条数据过一遍过了门的数据类型才真正成立。常用字段怎么写字符串、数字、对象、数组四个高频字段类型每种记住一两个核心方法就够。z.string().email(); // 基础格式校验 z.string().regex(/^\d{11}$/, 需要 11 位手机号); // 自定义格式 z.number().int().min(0).max(150); // 数字范围对象和数组则是容器注意它们各自的默认行为const User z.object({ name: z.string(), vip: z.boolean().default(false), // 没传时补默认值不用到处写 || false }); z.array(z.number()).min(1); // 数组本身也有约束两个默认行为值得记住z.object会默默丢弃schema 里没声明的字段严格是它的保护色数组元素类型不对时错误会精确指到具体下标排查不用猜。场景实战表单、API、环境变量三个覆盖 90% 日常需求的场景每个都是可以直接搬走的写法。1. 登录表单验证const LoginForm z.object({ account: z.string().email().or(z.string().regex(/^1\d{10}$/)), password: z.string().min(8, 密码至少 8 位), remember: z.boolean().default(false), });点评.or()让邮箱和手机号二选一都能过校验逻辑全部集中在 schema 里组件层只负责渲染error。2. API 出入参如何校验const Query z.object({ page: z.coerce.number().int().min(1), // URL 里的参数永远是字符串 q: z.string().optional(), }); // 出参用同一套方式定义响应结构就不怕被人偷偷改 const Resp z.object({ code: z.literal(0), data: z.array(QueryItem) });点评入口用safeParse失败时把error.issues转成 400 返回让脏数据死在门口而不是数据库里。3. 环境变量与配置解析process.env里每个值都是字符串直接当数字用迟早翻车const Config z.object({ PORT: z.coerce.number().int().min(1).max(65535), // 把 8080 变成 8080 NODE_ENV: z.enum([development, production]), FEATURE_FLAGS: z.record(z.string(), z.number()).default({}), }); const config Config.parse(process.env); // 启动即校验错配置当场拒绝启动点评z.coerce是处理外部字符串数据的瑞士军刀配置在进程启动时解析一次比运行时零散转换更可控。进阶招式判别联合、递归、强转判别联合——当数据看一个字段就知道它是什么时const Payment z.discriminatedUnion(type, [ z.object({ type: z.literal(wechat), openId: z.string() }), z.object({ type: z.literal(card), last4: z.string().regex(/^\d{4}$/) }), ]);运行时按type精确分派错误消息也指向具体分支比z.union的都不像友好得多。递归模式——评论套评论这种树形结构用 getter 自引用即可不需要z.lazyconst Comment z.object({ text: z.string(), get replies() { return z.array(Comment).default([]); // 返回类型而非实例避开初始化顺序问题 }, });类型强转——z.coerce.date(2024-01-01)得到Date对象z.coerce.number(42)得到42。凡是数据来自字符串世界HTTP、CLI、表单优先想coerce而不是手写转换函数。生态集成接上表单框架与 tRPCReact Hook Form装hookform/resolvers把 schema 交给zodResolver。const form useForm({ resolver: zodResolver(LoginForm), });接完之后你得到两样东西提交前自动跑验证errors对象按字段路径组织直接渲染到对应输入框下表单值的类型也是z.infer推出来的不用手写第二份 interface。tRPC每个 procedure 声明.input()和.output()两端各放一个 Zod schema。服务端先验入参客户端拿到响应后还能按output再验一遍——类型安全从你的类型定义一路贯通到对端的服务。避坑清单z.object默认丢弃未知字段。需要保留时用z.looseObject排查我的字段去哪了时先怀疑这一点。取类型用z.infertypeof Schema。别手动写一遍类型schema 一改你的接口类型就悄悄过期。URL 参数、环境变量都是字符串。数字用z.coerce.number()日期用z.coerce.date()别裸用z.number()。顶层入口用safeParse。parse抛错在路由层容易漏接变成一次没意义的 500。schema 定义放独立文件。它要同时被组件、路由、测试 import重复创建 schema 实例也是白白浪费。继续深入Zod 的核心逻辑不复杂schema 是数据形状的安检门parse/safeParse是过门的两种姿势类型推断是过关后的附赠。先把这套用在你的下一个接口上脏数据从此进不了门。想再往下钻有三个入口核心实现源码 看每个 schema 是怎么落地的v4 测试目录 是最好的用法词典几乎每种边界情况都有用例官方文档 则是查 API 细节的第一站。【免费下载链接】zodTypeScript-first schema validation with static type inference项目地址: https://gitcode.com/GitHub_Trending/zo/zod创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考