type
status
date
slug
summary
tags
category
icon
password
📘 使用 @tanstack/react-form + Zod 实现前后端统一 API 校验
在现代 React 应用中，表单校验与 API 请求往往是一个痛点：前端需要给用户即时反馈错误，后端也 必须 再次校验请求数据，以防止恶意或意外不合规的数据进入系统。理想状态下，我们希望：
- 前端和后端 使用同一份校验规则（避免重复维护）
- 校验规则既能在运行时生效，也能让 TypeScript 提供类型安全
- 表单体验流畅、代码可维护、类型安全
在这里，我们选择组合使用 Zod 与 TanStack Form：
- 用 Zod 定义 schema（校验规则 + 类型推导）
- 用 TanStack Form 管理 React 表单状态、校验、提交流程
- 后端也使用 Zod 同样的 schema 来校验 API 请求
这样就实现 “前端校验 + 类型安全 +后端验证” 的完整闭环。
🧠 一、为什么选择 TanStack Form + Zod
Zod 的优点
- 定义 schema：
z.object({ ... })，可设置类型、最小长度、邮箱格式、数值范围等。
- 运行时校验：
schema.parse(data)会在运行时抛出错误（ZodError）。
- 类型推导：
type T = z.infer<typeof schema>，自动生成 TS 类型。
- 前后端通用：你可以把 schema 放在一个共享模块里。
TanStack Form 的优势
- 最新、类型安全、由 TanStack 团队出品，有强类型优先设计。 TanStack+3LogRocket Blog+3TanStack+3
- 支持 React 以外多框架，不过在 React 中使用非常流畅。 TanStack+1
- 支持各种校验时机（onChange、onBlur、onSubmit）、支持异步验证、支持字段数组等。 TanStack+1
- 当表单规模大、或你希望校验逻辑与类型保持严格一致时，比一些传统表单库（如 React Hook Form）更具优势。 LogRocket Blog
因此，组合这两者可以做到：一份 schema，前端用它 + 表单库；后端也用它做最终验证，从而实现少代码、类型安全、统一规则。
二、安装依赖
在 Next.js 项目中安装：
三、定义Schema
四、编写@tanstack/react-query的provider
然后在layout.tsx中包裹住{children}
五、测试表单代码
六、后端API验证逻辑
🤗 总结归纳
步骤 | 说明 |
1️⃣ 定义 schema | 用 z.object() 指定字段和规则 |
2️⃣ 调用 .parse() | 校验请求数据 |
3️⃣ 捕获 ZodError | 统一返回错误 |
4️⃣ 使用 z.infer | 自动生成 TS 类型 |
5️⃣ 可封装成函数 | 提高复用性 |
📎 参考文章
有关Notion安装或者使用上的问题，欢迎您在底部评论区留言，一起交流~
- Author:Tao Chen
- URL:https://www.nextdaddy.cn/article/2919b3f5-e6ae-80b1-8880-d8c2e38fa46f
- Copyright:All articles in this blog, except for special statements, adopt BY-NC-SA agreement. Please indicate the source!
