用途
本技能致力于实现端到端类型安全,使缺陷在编译期被发现而非运行期。适用场景包括:构建类型安全的 API(REST、RPC、GraphQL)、校验用户输入与外部数据、确保数据库查询类型安全、创建端到端类型化的全栈应用、从 JavaScript 迁移至 TypeScript,以及实施严格校验规则。
主要能力
Zod 运行时校验
用 z.object 定义 schema,通过 z.infer 从 schema 推导 TypeScript 类型;使用 .safeParse() 优雅处理错误,或对已知可信数据使用 .parse()。支持字符串/数字/枚举/记录/日期等类型、.default() 默认值、.transform() 数据转换、.refine() 自定义细化校验、判别联合(z.discriminatedUnion)与递归类型(z.lazy)。
tRPC 类型安全 API
服务端用 initTRPC 与 t.procedure 定义查询和变更,输入由 Zod 校验;导出 AppRouter 类型后,客户端通过 createTRPCProxyClient<AppRouter> 获得完全类型化的调用,包含输入参数与返回值类型。与 React 集成可用 createTRPCReact<AppRouter>() 配合 useQuery、useMutation。
Prisma 类型安全 ORM
在 schema.prisma 中定义模型与关系,使用 PrismaClient 执行 findUnique、create 等操作时,where、include、data 及返回结果均自动推导类型,关联查询结果也带类型。
TypeScript 5.7+ 特性
覆盖 const 类型参数、satisfies 操作符(校验对象符合某类型同时保留字面量类型)、装饰器等现代语法。
穷尽式类型检查
提供 assertNever(x: never) 辅助函数,在 switch 的 default 分支调用,使新增联合类型成员时编译期报错;用 as const satisfies Record<UnionType, Value> 保证映射覆盖全部成员;用处理器对象配合接口强制处理所有内容类型;还给出模板字面量类型与类型守卫的穷尽式示例。
品牌类型(Branded Types)
TypeScript 侧用 Zod 的 .brand<'UserId'>() 等创建不同类型的 ID,编译期阻止混用;Python 侧用 NewType 实现零运行时开销的编译期安全,并配合工厂函数做运行时校验。
Python 类型安全(ty)
介绍基于 Rust 的静态类型检查器 ty,给出从无类型字典中安全提取字段的模式:显式类型注解配合 isinstance() 收窄类型,必要时用 cast。
最佳实践
校验层面:在边界处校验、用 .safeParse() 优雅处理错误、提供清晰错误信息、启动时校验环境变量、用品牌类型区分 ID。类型层面:开启 strict: true 与 noUncheckedIndexedAccess、优先 unknown 而非 any、用类型守卫收窄、使用 typeof/ReturnType 推导、穷尽式 switch 配 assertNever、穷尽式 record 配 satisfies、TypeScript 用 Zod 品牌类型、Python 用 NewType、用显式注解加 isinstance() 提取字典。性能层面:复用 schema、对可信数据用 .parse()、启用 Prisma 查询优化、用 tRPC 批处理、适当缓存校验结果。
使用方式
资料以代码示例为主,涵盖 schema 定义与类型推导、tRPC 服务端路由与客户端调用、Prisma 查询、穷尽式检查写法、品牌类型写法,以及一个 Next.js 后端路由、共享 router、React 前端组件组成的全栈示例。文档还列出常见反模式:不要使用不完整的 switch、不要用无 assertNever 的 default、不要用 if-else 链处理联合类型,应使用配 assertNever 的 switch。
适用场景与限制
适用于需要严格类型保障的全栈或后端项目,尤其适合 TypeScript 与 Python 混合技术栈。限制方面:资料未提供该技能的安装命令、配置方式、收费信息、更新时间以外的版本细节,也未说明与具体框架版本之外的环境要求;ty 相关内容仅为模式示例,未给出完整配置说明;Zod、tRPC、Prisma、TypeScript 的完整能力需参阅各自官方文档。