Redwood 教程:保存数据——从 Contact 模型到表单提交的完整数据写入实战
Redwood 教程:保存数据——从 Contact 模型到表单提交的完整数据写入实战
本篇教程带你走完 Redwood 中"保存数据"的完整闭环:从在 schema.prisma 中定义 Contact 数据模型、执行数据库迁移,到通过 SDL 与 Service 暴露 GraphQL 的 createContact mutation,再到前端表单用 useMutation 提交数据,最后用 loading 禁用、Toast 通知、Service Validations 与 <FormError> 打磨出健壮的用户体验。读完本文,你将掌握 Redwood 全栈数据写入的标准姿势,并理解 @requireAuth/@skipAuth 指令、"secure by default" 设计理念以及 Service 层业务校验的底层原理。本文基于仓库中的官方教程 saving-data.md 展开,并结合源码实现进行纵深讲解。
添加 Contact 模型
打开 api/db/schema.prisma,在现有的 Post 模型之后添加一个 Contact 模型。这是 Redwood 应用数据层的起点——所有数据库表结构都由 Prisma Schema 定义:
datasource db {
provider = "sqlite"
url = env("DATABASE_URL")
}
generator client {
provider = "prisma-client-js"
binaryTargets = "native"
}
model Post {
id Int @id @default(autoincrement())
title String
body String
createdAt DateTime @default(now())
}
// highlight-start
model Contact {
id Int @id @default(autoincrement())
name String
email String
message String
createdAt DateTime @default(now())
}
// highlight-end
Contact 模型包含四个字段:自增主键 id、联系人姓名 name、邮箱 email、留言内容 message,以及自动记录创建时间的 createdAt。这些字段全部是必填的 String 类型。
:::tip 可选字段的写法
若要将某个字段标记为可选(即允许 NULL 作为值),可在数据类型后加问号,例如 name String?。这样 name 的值既可以是 String 也可以是 NULL。
:::
创建并应用迁移
模型定义好后,运行 Prisma 迁移命令:
yarn rw prisma migrate dev
按提示为这次迁移命名,例如 create contact。该命令会为 Contact 表生成迁移 SQL 并应用到开发数据库,同时重新生成 Prisma Client,让 db.contact 在 Service 中可用。
创建 SDL 与 Service
有了数据模型,接下来创建 GraphQL 接口来访问这张表。scaffold 命令其实一直在背后使用 generate 命令,这里我们直接使用它:
yarn rw g sdl Contact
与 scaffold 一样,这条命令会在 api 目录下生成几个新文件:
api/src/graphql/contacts.sdl.{js,ts}:以 GraphQL 的 Schema Definition Language(SDL)定义 GraphQL schemaapi/src/services/contacts/contacts.{js,ts}:包含应用的业务逻辑(同时生成关联的测试文件)
还记得 Side Quest: How Redwood Deals with Data 中的讨论吗?SDL 文件中的查询(queries)和变更(mutations)会自动映射到 Service 中定义的解析器(resolvers)。因此生成 SDL 文件时一定会配套生成 Service 文件——两者相互依赖。
打开 api/src/graphql/contacts.sdl.{js,ts},你会看到与 Post scaffold 生成的完全一致的 Query 和 Mutation 类型结构:Contact、CreateContactInput、UpdateContactInput 三个类型,包含 contacts 和 contact 的 Query 类型,以及包含 createContact、updateContact 和 deleteContact 的 Mutation 类型。
SDL 文件内容解析
export const schema = gql`
type Contact {
id: Int!
name: String!
email: String!
message: String!
createdAt: DateTime!
}
type Query {
contacts: [Contact!]! @requireAuth
contact(id: Int!): Contact @requireAuth
}
input CreateContactInput {
name: String!
email: String!
message: String!
}
input UpdateContactInput {
name: String
email: String
message: String
}
type Mutation {
createContact(input: CreateContactInput!): Contact! @requireAuth
updateContact(id: Int!, input: UpdateContactInput!): Contact! @requireAuth
deleteContact(id: Int!): Contact! @requireAuth
}
`
TypeScript 版本的内容完全一致,仅文件后缀不同(contacts.sdl.ts)。
@requireAuth 与 @skipAuth:secure by default
Query 和 Mutation 类型后面跟的 @requireAuth 是一个 schema 指令(schema directive),意思是:访问这个 GraphQL 查询前,用户必须已通过认证。
目前我们还没有添加认证,所以这个指令暂时没有任何效果——任何人都能查询它,无论是否登录。原因在于:在搭建认证系统之前,@requireAuth 背后的函数始终返回 true。正如原文档所说:"为了不让新应用产生令人沮丧的错误,@requireAuth 指令在设置认证系统之前只是简单地返回 true,设置之后才会用真实的逻辑判断用户是否登录并按预期行事。"
值得一提的是,Redwood 在架构上对指令做了抽象:源码 makeDirectives.ts 中提供了 createValidatorDirective 与 createTransformerDirective 两个工厂函数,requireAuth/skipAuth 就是基于它们构建的内置指令。而 useRedwoodDirective 插件的测试用例(见 useRedwoodDirective.test.ts)则详细验证了 requireAuth 会拒绝未授权执行、skipAuth 会放行、带 roles 参数的 requireAuth 会校验角色等行为。
CreateContactInput 与 UpdateContactInput 的设计
CreateContactInput 和 UpdateContactInput 是什么?Redwood 遵循 GraphQL 官方建议,在 mutation 中使用 Input Types 而非逐个列出所有可设置字段。
schema.prisma中必填的字段,在CreateContactInput中也必填(没有它们就无法创建合法记录);UpdateContactInput中没有任何字段是显式必填的,因为你可能只想更新一个、两个或全部字段。另一种做法是为每种字段组合单独创建 Input 类型,但 Redwood 认为只保留一个 update input 类型是对开发者体验更优的折中。
:::info id 与 createdAt 不在 Input 类型中
Redwood 假定你的代码不会试图给 id 或 createdAt 字段赋值,所以把它们排除在 Input 类型之外。但如果你的数据库允许手动设置这两个字段,可以自行修改 CreateContactInput 或 UpdateContactInput 把它们加进去。
:::
由于 schema.prisma 中的所有列都是必填的,它们对应的 GraphQL 类型也通过数据类型后的 ! 后缀标记为必填(如 name: String!)。
:::tip SDL 与 Prisma 的可选性语法区别
GraphQL 的 SDL 语法要求字段必填时多加一个 !;而 schema.prisma 语法要求字段非必填时多加一个 ?。两者恰好相反,注意区分。
:::
无显式 Resolver 的映射约定
正如 Side Quest: How Redwood Deals with Data 所述,SDL 文件中没有显式定义 resolver。Redwood 遵循一个简单的命名约定:sdl 文件(api/src/graphql/contacts.sdl.{js,ts})的 Query 和 Mutation 类型中的每个字段,都会映射到 services 文件(api/src/services/contacts/contacts.{js,ts})中同名的一个函数。
:::tip 只读 SDL 的快捷方式
如果你只需要一个简单的只读 SDL,可以跳过创建 create/update/delete mutation,给 SDL 生成器传一个标志:
yarn rw g sdl Contact --no-crud
这样你只会得到一个返回全部数据的 contacts 查询。
:::
精简 mutation:只保留 createContact
联系页面只需要 createContact。它接受单个变量 input,一个符合 CreateContactInput 结构的对象,即 { name, email, message }。
这个 mutation 应该允许任何人访问(访客要能匿名留言),所以把 @requireAuth 改成 @skipAuth。@skipAuth 表示不要求认证,允许任何人匿名提交留言。
注意:每个 Query 和 Mutation 至少需要一个 schema 指令,否则会报错。Redwood 拥抱 "secure by default" 的理念——即使你不做任何特殊防护,也尽量保证应用安全:在这种情况下,抛出一个错误远比把用户数据意外暴露到互联网上安全得多。
:::info 巧合且合适
默认指令 @requireAuth 恰好正是 contacts 查询(返回所有留言)所需要的——只有博客的主人应该有权读取全部留言。
:::
我们不打算让任何人更新或删除留言,所以把这些字段整个移除。修改后的 SDL 文件如下(JavaScript 与 TypeScript 版本一致):
export const schema = gql`
type Contact {
id: Int!
name: String!
email: String!
message: String!
createdAt: DateTime!
}
type Query {
contacts: [Contact!]! @requireAuth
contact(id: Int!): Contact @requireAuth
}
input CreateContactInput {
name: String!
email: String!
message: String!
}
// highlight-start
type Mutation {
createContact(input: CreateContactInput!): Contact! @skipAuth
}
// highlight-end
`
SDL 文件到此为止,接下来看 Service。
Service:业务逻辑的载体
import { db } from 'src/lib/db'
export const contacts = () => {
return db.contact.findMany()
}
export const contact = ({ id }) => {
return db.contact.findUnique({
where: { id },
})
}
export const createContact = ({ input }) => {
return db.contact.create({
data: input,
})
}
export const updateContact = ({ id, input }) => {
return db.contact.update({
data: input,
where: { id },
})
}
export const deleteContact = ({ id }) => {
return db.contact.delete({
where: { id },
})
}
TypeScript 版本会额外引入生成的类型,将每个函数标注为对应 resolver 类型:
import type { QueryResolvers, MutationResolvers } from 'types/graphql'
import { db } from 'src/lib/db'
export const contacts: QueryResolvers['contacts'] = () => {
return db.contact.findMany()
}
export const contact: QueryResolvers['contact'] = ({ id }) => {
return db.contact.findUnique({
where: { id },
})
}
export const createContact: MutationResolvers['createContact'] = ({ input }) => {
return db.contact.create({
data: input,
})
}
export const updateContact: MutationResolvers['updateContact'] = ({ id, input }) => {
return db.contact.update({
data: input,
where: { id },
})
}
export const deleteContact: MutationResolvers['deleteContact'] = ({ id }) => {
return db.contact.delete({
where: { id },
})
}
非常直观:createContact() 接收 input 参数,直接把它透传给 Prisma 的 create() 调用。
updateContact 和 deleteContact 如果不想保留可以删掉——反正 GraphQL 层已经没有对应的字段了,客户端无法调用它们。
GraphQL Playground:在实现 UI 前调试 API
在把功能接入 UI 之前,Redwood 提供了一个非常好用的 GUI。运行 yarn redwood dev(或 yarn rw dev)时,实际上同时启动了第二个进程。打开新浏览器标签页访问 http://localhost:8911/graphql,这是 GraphQL Yoga 提供的 GraphiQL——一个基于 Web 的 GraphQL API 图形界面。
左侧选择 "Docs" 标签页并点击 query: Query,可以看到由我们的 SDL 文件定义的完整 schema!Playground 会解析这些定义并给出自动补全提示,帮助我们从零构建查询。例如尝试获取数据库中所有帖子的 ID:在左侧输入查询语句,点击 "Play" 按钮执行。
GraphQL Playground 非常适合在编码中途排查问题——无论是 API 层还是 Web 层的拼写错误,都可以先在原始形态下实验和调用 API。
前端创建 Contact:定义 Mutation 并调用
后端的 GraphQL mutation 已经就绪,剩下的就是在前端调用它。与表单相关的所有内容都在 ContactPage 中,所以 mutation 调用就放在这里。
首先把 mutation 定义为一个常量(可以定义在组件外部,紧跟 import 语句之后):
import { MetaTags } from '@redwoodjs/web'
import {
FieldError,
Form,
Label,
TextField,
TextAreaField,
Submit,
} from '@redwoodjs/forms'
// highlight-start
const CREATE_CONTACT = gql`
mutation CreateContactMutation($input: CreateContactInput!) {
createContact(input: $input) {
id
}
}
`
// highlight-end
const ContactPage = () => {
const onSubmit = (data) => {
console.log(data)
}
return (
<>
<MetaTags title="Contact" description="Contact page" />
<Form onSubmit={onSubmit} config={{ mode: 'onBlur' }}>
<Label name="name" errorClassName="error">
Name
</Label>
<TextField
name="name"
validation={{ required: true }}
errorClassName="error"
/>
<FieldError name="name" className="error" />
<Label name="email" errorClassName="error">
Email
</Label>
<TextField
name="email"
validation={{
required: true,
pattern: {
value: /^[^@]+@[^.]+\..+$/,
message: 'Please enter a valid email address',
},
}}
errorClassName="error"
/>
<FieldError name="email" className="error" />
<Label name="message" errorClassName="error">
Message
</Label>
<TextAreaField
name="message"
validation={{ required: true }}
errorClassName="error"
/>
<FieldError name="message" className="error" />
<Submit>Save</Submit>
</Form>
</>
)
}
export default ContactPage
我们引用了 Contacts SDL 中定义的 createContact mutation,向它传入一个包含 name、email 和 message 实际值的 input 对象。TypeScript 版本在此基础上增加一个 FormValues 接口,并为 onSubmit 标注 SubmitHandler<FormValues> 类型。
useMutation:执行 mutation 的 Hook
接下来调用 Redwood 提供的 useMutation hook,它允许我们在合适的时机执行 mutation(别忘了 import 它):
import { MetaTags, useMutation } from '@redwoodjs/web'
// ...其余 import 不变
const ContactPage = () => {
const [create] = useMutation(CREATE_CONTACT)
const onSubmit = (data) => {
console.log(data)
}
// ...return 不变
}
TypeScript 版本中,useMutation 会使用 Redwood 自动生成的类型:
import {
CreateContactMutation,
CreateContactMutationVariables,
} from 'types/graphql'
// ...
const ContactPage = () => {
const [create] = useMutation<
CreateContactMutation,
CreateContactMutationVariables
>(CREATE_CONTACT)
// ...
}
:::tip 关于自动生成的类型
只要开发服务器在运行(或手动运行 yarn rw generate types),Redwood 就会为 GraphQL 查询和 mutation 自动生成类型。一旦你定义了 CreateContactMutation(GraphQL 那个),Redwood 就会据此生成 CreateContactMutation 和 CreateContactMutationVariables 类型。更深的内容可参考 Generated Types。
:::
create 是一个调用 mutation 的函数,它接收一个带 variables 键的对象,其中再包含一个 input 键。例如可以这样调用:
create({
variables: {
input: {
name: 'Rob',
email: 'rob@redwoodjs.com',
message: 'I love Redwood!',
},
},
})
如果你还记得 <Form> 会把所有字段打包成一个以字段名作键的对象,就会发现 onSubmit 中接收到的 data 对象恰好已经是 input 需要的格式!
因此可以直接把 onSubmit 改成调用 mutation:
const ContactPage = () => {
const [create] = useMutation(CREATE_CONTACT)
const onSubmit = (data) => {
create({ variables: { input: data } })
}
// ...return 不变
}
试着填写并提交表单——数据库里应该已经有新的 Contact 记录了!可以通过 Prisma Studio 或上面提到的 GraphQL Playground 验证。
从源码层面看,Redwood 的 useMutation 实际来自 Apollo Client:在 packages/web/src/apollo/index.tsx 中,RedwoodApolloProvider 通过 GraphQLHooksProvider 把 Apollo 的 useQuery、useMutation、useSubscription 等 hooks 注入应用上下文。同时它还通过 Apollo Link 链路(withToken → authMiddleware → updateDataApolloLink → 终止 link)自动处理 token 注入、认证头、错误追踪与 HTTP 上传。
改进联系表单
表单能工作了,但目前还有几个问题:
- 多次点击提交按钮会产生多次提交
- 用户不知道提交是否成功
- 如果服务器端出错,我们无法通知用户
逐一解决。
提交时禁用 Save 按钮
useMutation hook 除了返回调用函数外,还返回更多内容。我们可以从返回的数组中解构第二个元素——其中我们关心的是 loading 和 error:
const ContactPage = () => {
const [create, { loading, error }] = useMutation(CREATE_CONTACT)
const onSubmit = (data) => {
create({ variables: { input: data } })
}
// ...return 不变
}
现在通过 loading 可以知道数据库调用是否仍在进行。修复重复提交问题的简单做法:当响应仍在进行时禁用提交按钮,把 "Save" 按钮的 disabled 属性设为 loading:
return (
// ...
<Submit disabled={loading}>Save</Submit>
// ...
)
开发环境下提交太快可能看不出区别,但可以通过 Chrome Web Inspector 的 Network 面板启用网络限速(network throttling)模拟慢速连接——你会看到等待响应时 "Save" 按钮被禁用了一两秒。
提交成功通知
接下来显示一条通知,让用户知道提交成功。Redwood 内置了 react-hot-toast,可以快速在页面上显示弹出通知。
useMutation 接受一个选项对象作为第二个参数。其中一个选项是回调函数 onCompleted,mutation 成功完成后会被调用。我们用这个回调调用 toast() 函数,把消息显示到 <Toaster> 组件中。
给 useMutation 加上 onCompleted 回调,并在 return 中、<Form> 之前放入 <Toaster> 组件:
import { MetaTags, useMutation } from '@redwoodjs/web'
import { toast, Toaster } from '@redwoodjs/web/toast'
// ...其余 import 不变
const ContactPage = () => {
const [create, { loading, error }] = useMutation(CREATE_CONTACT, {
onCompleted: () => {
toast.success('Thank you for your submission!')
},
})
const onSubmit = (data) => {
create({ variables: { input: data } })
}
return (
<>
<MetaTags title="Contact" description="Contact page" />
<Toaster />
<Form onSubmit={onSubmit} config={{ mode: 'onBlur' }}>
{/* ...表单字段不变 */}
<Submit disabled={loading}>Save</Submit>
</Form>
</>
)
}
完整文档可参考 toast-notifications.md。
显示服务器错误:Service Validations 与 FormError
接下来向用户展示服务器端错误。到目前为止我们只通知了客户端错误:字段缺失或格式不正确。但如果存在服务器端约束,<Form> 无从知晓,我们仍然需要让用户知道出了问题。
前端有 email 校验,但任何一个合格的开发者都知道:永远不要信任客户端(never trust the client)。为了确保即使有人绕过前端校验,也不会有坏数据进入数据库,需要在 api 侧也加上 email 校验。
:::info 为什么某些字段不需要服务器端必填校验?
为什么 name、email、message 的存在性不需要服务器端校验?因为 GraphQL 已经替我们做了!还记得 SDL 文件中 Contact 类型的 String! 声明吗?它给字段加了一条约束:这些字段一到 api 侧就不能是 null。如果是 null,GraphQL 会拒绝请求并抛错给客户端。
但是,如果你在一个 Service 内部调用另一个 Service,就不会有任何校验!GraphQL 只在"外部"发起请求时(比如浏览器)介入。如果你确实想确保字段存在或格式正确,需要在 Service 内部添加校验。这样无论谁调用这个 Service 函数(GraphQL 还是另一个 Service),数据都保证被检查。
我们还有一层免费的额外校验:因为 name、email、message 在 schema.prisma 中被设为必填,数据库本身会阻止任何 null 被写入。不过通常不建议只依赖数据库做输入校验:数据格式应该是业务逻辑的关切,而在 Redwood 应用中,业务逻辑就住在 Service 里!
:::
我们之前讨论过业务逻辑属于 Service 文件,这正是完美例证。由于输入校验是常见需求,Redwood 提供了 Service Validations。
在 contacts Service 中调用新的 validate 函数,确保 email 字段确实是邮箱格式:
// highlight-next-line
import { validate } from '@redwoodjs/api'
// ...
export const createContact = ({ input }) => {
// highlight-next-line
validate(input.email, 'email', { email: true })
return db.contact.create({ data: input })
}
TypeScript 版本一致,只是 createContact 标注了 MutationResolvers['createContact'] 类型。
这里有三个 email 引用,逐一解释:
- 第一个参数是我们要检查的值。这里
input包含全部联系数据,其中email的值就是检查目标 - 第二个参数是
<TextField>的name属性,这样 Redwood 就知道页面上哪个输入框有错误 - 第三个参数是一个包含要调用的**校验指令(validation directives)**的对象。这里只有一个,
email: true表示使用内置的 email 校验器
所以当 createContact 被调用时,会先校验输入,只有没有抛错才继续在数据库中创建记录。
从源码看,validate 的实现位于 packages/api/src/validations/validations.ts。它内部维护一个 VALIDATORS 表,内置 absence、acceptance、email、exclusion、format、inclusion、length、numericality、presence、custom 等校验器,并根据校验类型抛出对应的 XxxValidationError(如 EmailValidationError)。其中 email 校验器使用的正则非常宽松:/^[^@\s]+@[^.\s]+\.[^\s]+$/——官方邮箱正则约有 6300 个字符,Redwood 认为这个简化版本已经足够,如需更严格可以用 format 校验器自定义正则。
暂时移除客户端校验以测试服务端校验
目前我们甚至无法测试服务器端校验,因为 <TextField> 的 validation 属性已经在客户端检查邮箱格式了。先暂时移除它,让坏数据能送到服务器:
<TextField
name="email"
validation={{
required: true,
- pattern: {
- value: /^[^@]+@[^.]+\..+$/,
- message: 'Please enter a valid email address',
- },
}}
errorClassName="error"
/>
还记得之前说 <Form> 还有一招吗?来了!
添加一个 <FormError> 组件,传入从 useMutation 拿到的 error 常量并加一点 wrapperClassName 样式(别忘了 import)。同时把 error 也传给 <Form>,让它建立 context:
import {
FieldError,
Form,
// highlight-next-line
FormError,
Label,
TextField,
TextAreaField,
Submit,
} from '@redwoodjs/forms'
// ...
return (
<>
<MetaTags title="Contact" description="Contact page" />
<Toaster />
<Form onSubmit={onSubmit} config={{ mode: 'onBlur' }} error={error}>
<FormError error={error} wrapperClassName="form-error" />
{/* ...其余字段不变 */}
<Submit disabled={loading}>Save</Submit>
</Form>
</>
)
现在用无效邮箱提交一条消息:页面顶部会以通俗易懂的英文显示错误信息,同时出错的字段本身也会被高亮,和行内校验一样!顶部信息框对短表单来说可能有点多余,但对多屏长表单至关重要——用户能在同一处看到错误摘要,不必在冗长表单里到处找红框。如果不需要顶部信息框,直接移除 <FormError>,字段仍然会按预期高亮。
从源码看,<Form>(packages/forms/src/Form.tsx)会读取 error?.graphQLErrors?.<a href="https://link.gitcode.com/i/ae604956c43ff50d186f29948afb2cd0" target="_blank">0]?.extensions?.properties?.messages 存入 ServerErrorsContext,而 <FormError>([packages/forms/src/FormError.tsx)则负责渲染错误信息框,二者共同构成了"服务器错误 → 表单上下文 → 页面展示"的完整链路。
:::info FormError 的样式选项
<FormError> 提供了多个样式选项,分别作用于消息的不同部分:
wrapperStyle/wrapperClassName:整个消息的容器titleStyle/titleClassName:"Errors prevented this form..." 标题listStyle/listClassName:包含错误列表的<ul>listItemStyle/listItemClassName:包裹每条错误的<li>
:::
Service Validations 的更多玩法
这只是 Service Validations 能力的冰山一角。你可以做更复杂的校验,包括在单次调用中组合多个指令。假设有一个代表 Car 的模型,用户可以在我们的高端汽车售卖网站上提交车辆。如何确保只收到精品车?Service validations 允许我们仅用内置的 validate() 调用就精确限制可提交的值,无需任何自定义检查:
export const createCar = ({ input }) => {
validate(input.make, 'make', {
inclusion: ['Audi', 'BMW', 'Ferrari', 'Lexus', 'Tesla'],
})
validate(input.color, 'color', {
exclusion: { in: ['Beige', 'Mauve'], message: "No one wants that color" }
})
validate(input.hasDamage, 'hasDamage', {
absence: true
})
validate(input.vin, 'vin', {
format: /[A-Z0-9]+/,
length: { equal: 17 }
})
validate(input.odometer, 'odometer', {
numericality: { positive: true, lessThanOrEqual: 10000 }
})
return db.car.create({ data: input })
}
对照源码 validations.ts,各校验器的能力非常清晰:
inclusion:值必须在给定列表内(可用in指定列表,caseSensitive控制大小写敏感,默认敏感)exclusion:值不能等于列表中的任何一项(与inclusion相反)absence:字段必须不存在,即必须是null或undefined(allowEmptyString: true时空字符串也算"不存在")format:值必须匹配给定正则(可用{ pattern: /.../ }形式)length:支持min、max、equal、between(如{ between: [2, 255] })numericality:支持integer、lessThan、lessThanOrEqual、greaterThan、greaterThanOrEqual、equal、otherThan、even、odd、positive、negative
你仍然可以嵌入自己的自定义校验逻辑,并让错误以与内置校验相同的方式处理:
validateWith(() => {
const oneWeekAgo = new Date()
oneWeekAgo.setDate(oneWeekAgo.getDate() - 7)
if (input.lastCarWashDate < oneWeekAgo) {
throw new Error("We don't accept dirty cars")
}
})
这样就能保证你不会收到一辆破旧老爷车!
从源码看,validateWith 的默认导出是异步版本(内部 await func()),另有一个同步版本 validateWithSync。其设计动机在源码注释里写得很清楚:为什么不直接写自己的函数?因为 GraphQL 会吞掉它,只给客户端返回 "Something went wrong"。而 validateWith 会捕获你抛出的任何自定义错误,把它转换成 ServiceValidationError,从而让真实的错误信息能显示给客户端。此外 validations.ts 还导出了 validateUniqueness,它把校验包在数据库事务中,可配合 $self(更新时排除自身)与 $scope(在子集内校验唯一)使用,适合邮箱、用户名等唯一性约束场景。
最后一步:提交后清空表单
由于提交后没有重定向,至少应该清空表单字段。这需要用到 React Hook Form 提供的 reset() 函数,但 <Form> 的基础用法(就像我们目前的用法)拿不到它。
Redwood 包含一个 useForm() hook(来自 React Hook Form),平时由 <Form> 在内部调用。要重置表单,我们需要自己调用这个 hook。但 useForm() 提供的功能仍然需要被 Form 使用。做法如下。
首先 import useForm:
import {
FieldError,
Form,
FormError,
Label,
Submit,
TextAreaField,
TextField,
// highlight-next-line
useForm,
} from '@redwoodjs/forms'
在组件内部调用它:
const ContactPage = () => {
// highlight-next-line
const formMethods = useForm()
//...
最后让 <Form> 使用我们从 useForm() 拿到的 formMethods,而不是自己内部调用:
return (
<>
<Toaster />
<Form
onSubmit={onSubmit}
config={{ mode: 'onBlur' }}
error={error}
// highlight-next-line
formMethods={formMethods}
>
// ...
现在可以在调用 toast() 之后对 formMethods 调用 reset():
const [create, { loading, error }] = useMutation(CREATE_CONTACT, {
onCompleted: () => {
toast.success('Thank you for your submission!')
// highlight-next-line
formMethods.reset()
},
})
从源码 Form.tsx 可以印证:<Form> 内部调用 useForm(config) 得到 hookFormMethods,然后 const formMethods = propFormMethods || hookFormMethods——即你传入的 formMethods 会优先于内部自动创建的那份。config 只在 useForm() 由 <Form> 内部调用时才会被自动传入。
:::caution 别忘了把客户端校验加回来
现在可以把邮箱校验放回 <TextField> 了,但建议保留服务器端校验,以防万一。
:::
:::info 为什么手动 useForm 后 onBlur 失效了?
你可能注意到,一旦自己调用 useForm(),onBlur 表单配置就失效了。因为 Redwood 之前在后台调用 useForm() 并自动把 <Form> 上的 config 属性传进去。现在 Redwood 不再替你调用 useForm() 了,如果需要传递某些选项就得手动来:
const ContactPage = () => {
const formMethods = useForm({ mode: 'onBlur' })
//...
:::
完整页面代码
把上述所有改进合并,完整的联系页面如下(JavaScript 版本;TypeScript 版本在此基础上增加 FormValues 接口、SubmitHandler 类型与生成的 CreateContactMutation 类型标注):
import { MetaTags, useMutation } from '@redwoodjs/web'
import { toast, Toaster } from '@redwoodjs/web/toast'
import {
FieldError,
Form,
FormError,
Label,
Submit,
TextAreaField,
TextField,
useForm,
} from '@redwoodjs/forms'
const CREATE_CONTACT = gql`
mutation CreateContactMutation($input: CreateContactInput!) {
createContact(input: $input) {
id
}
}
`
const ContactPage = () => {
const formMethods = useForm()
const [create, { loading, error }] = useMutation(CREATE_CONTACT, {
onCompleted: () => {
toast.success('Thank you for your submission!')
formMethods.reset()
},
})
const onSubmit = (data) => {
create({ variables: { input: data } })
}
return (
<>
<MetaTags title="Contact" description="Contact page" />
<Toaster />
<Form
onSubmit={onSubmit}
config={{ mode: 'onBlur' }}
error={error}
formMethods={formMethods}
>
<FormError error={error} wrapperClassName="form-error" />
<Label name="name" errorClassName="error">
Name
</Label>
<TextField
name="name"
validation={{ required: true }}
errorClassName="error"
/>
<FieldError name="name" className="error" />
<Label name="email" errorClassName="error">
Email
</Label>
<TextField
name="email"
validation={{
required: true,
pattern: {
value: /^[^@]+@[^.]+\..+$/,
message: 'Please enter a valid email address',
},
}}
errorClassName="error"
/>
<FieldError name="email" className="error" />
<Label name="message" errorClassName="error">
Message
</Label>
<TextAreaField
name="message"
validation={{ required: true }}
errorClassName="error"
/>
<FieldError name="message" className="error" />
<Submit disabled={loading}>Save</Submit>
</Form>
</>
)
}
export default ContactPage
这样就完成了!React Hook Form 提供了大量 <Form> 未暴露的功能。当你想用到这些功能时,可以自己调用 useForm(),但一定要把返回的对象(我们命名为 formMethods)作为 prop 传给 <Form>,这样校验和其他功能才能继续正常工作。
小结
至此,公共站点看起来相当不错了。回顾本篇的核心链路:
- 数据层:在
api/db/schema.prisma定义Contact模型,用yarn rw prisma migrate dev生成迁移 - API 层:
yarn rw g sdl Contact生成 SDL 与 Service,借助命名约定自动完成字段到 resolver 的映射;用@skipAuth开放匿名提交,用@requireAuth保护数据读取 - 前端:
useMutation执行createContact,配合loading防重复提交、toast做成功通知、validate()+<FormError>做双层校验与错误展示、useForm()+formMethods.reset()清空表单
下一步自然是管理功能:把创建和编辑帖子的功能移到某个管理后台区域,并放在登录之后,避免随便浏览 URL 的匿名用户创建垃圾内容——这正是 章节后续内容(若有)要解决的问题。本教程对应的完整源码位于 test-project 等测试项目中,可对照研读。