Redwood 教程:保存数据——从 Contact 模型到表单提交的完整数据写入实战

原创2026-09-23 11:56:571,847 阅读
文章标签:后端前端Web框架开发工具

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 目录下生成几个新文件:

  1. api/src/graphql/contacts.sdl.{js,ts}:以 GraphQL 的 Schema Definition Language(SDL)定义 GraphQL schema
  2. api/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 引用,逐一解释:

  1. 第一个参数是我们要检查的值。这里 input 包含全部联系数据,其中 email 的值就是检查目标
  2. 第二个参数是 <TextField> 的 name 属性,这样 Redwood 就知道页面上哪个输入框有错误
  3. 第三个参数是一个包含要调用的**校验指令(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>,这样校验和其他功能才能继续正常工作。

小结

至此,公共站点看起来相当不错了。回顾本篇的核心链路:

  1. 数据层:在 api/db/schema.prisma 定义 Contact 模型,用 yarn rw prisma migrate dev 生成迁移
  2. API 层:yarn rw g sdl Contact 生成 SDL 与 Service,借助命名约定自动完成字段到 resolver 的映射;用 @skipAuth 开放匿名提交,用 @requireAuth 保护数据读取
  3. 前端:useMutation 执行 createContact,配合 loading 防重复提交、toast 做成功通知、validate() + <FormError> 做双层校验与错误展示、useForm() + formMethods.reset() 清空表单

下一步自然是管理功能:把创建和编辑帖子的功能移到某个管理后台区域,并放在登录之后,避免随便浏览 URL 的匿名用户创建垃圾内容——这正是 章节后续内容(若有)要解决的问题。本教程对应的完整源码位于 test-project 等测试项目中,可对照研读。

登录后查看全文
redwood