Redwood 保存数据实战：从 Prisma 模型到联系表单的全栈闭环

Redwood 保存数据实战从 Prisma 模型到联系表单的全栈闭环【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood本指南是 Redwood 教程保存数据章节的完整实战讲解以博客的联系我们表单为用例从schema.prisma新增Contact数据模型开始依次打通数据库迁移、GraphQL SDL 与 Service 层、GraphQL Playground 调试、前端useMutation调用最后完成防重复提交、成功通知、服务端校验与表单重置等增强。读完你将掌握 Redwood 中数据如何从浏览器一路写入数据库的完整链路以及内置的 Service Validations 校验体系。第一步在 Prisma 中新增 Contact 模型打开api/db/schema.prisma在现有的Post模型之后新增一个Contact模型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()) } model Contact { id Int id default(autoincrement()) name String email String message String createdAt DateTime default(now()) }关于可选字段Prisma 的schema.prisma语法中若某字段允许为NULL需要在数据类型后面追加问号例如name String?表示name的值既可以是String也可以是NULL。这与 GraphQL 侧用!表示必填恰好相反两者容易混淆务必记清Prisma 用?表示非必填GraphQL SDL 用!表示必填。模型定义完成后创建并应用数据库迁移yarn rw prisma migrate dev为该迁移起一个名称例如create contact。迁移会生成对应的 SQL 变更并同步更新 Prisma Client。第二步生成 SDL 与 Service接下来为这张表创建 GraphQL 接口。用generate命令scaffold命令内部其实也复用了它yarn rw g sdl Contact该命令会在api目录下生成两类文件api/src/graphql/contacts.sdl.{js,ts}以 GraphQL Schema Definition LanguageSDL定义 GraphQL schemaapi/src/services/contacts/contacts.{js,ts}存放应用的业务逻辑同时会生成配套的测试文件。如 Side Quest: How Redwood Deals with Data 中所述SDL 文件中的查询与变更会自动映射到 Service 中定义的同名 resolver因此生成 SDL 时必然同时生成 Service 文件——两者互为依存。打开api/src/graphql/contacts.sdl.{js,ts}可以看到与 Post scaffold 相同的结构Contact、CreateContactInput、UpdateContactInput三种类型Query类型中的contacts与contact以及Mutation类型中的createContact、updateContact、deleteContactexport 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 } 理解requireAuth与 Input 类型Query与Mutation类型后面的requireAuth是一个 schema 指令validator directive含义是访问该 GraphQL 查询的用户必须已通过认证。在 Redwood 新项目中由于尚未接入任何认证方案该指令目前不会产生实际拦截效果——任何人都能查询无论是否登录因为未配置认证时requireAuth背后的函数恒返回true。仓库中可以直接看到这两个指令的实现。新项目模板里的 requireAuth 指令 会调用应用侧的requireAuth({ roles })可选地传入roles做角色校验而 skipAuth 指令 则是一个空实现直接放行export const schema gql Use to skip authentication checks and allow public access. directive skipAuth on FIELD_DEFINITION const skipAuth createValidatorDirective(schema, () { return })每个Query和Mutation至少需要一个 schema 指令否则会直接报错。这是 Redwood secure by default默认安全理念的体现宁可抛错也不要在开发者未做任何防护时把用户数据意外暴露到公网。什么是CreateContactInput/UpdateContactInputRedwood 遵循 GraphQL 官方关于 Input Types 的建议mutation 中不逐一列出每个可设置的字段而是整体接收一个 Input 对象。schema.prisma中必填的字段在CreateContactInput中同样必填缺少它们无法创建合法记录但UpdateContactInput中没有任何字段被显式标记为必填——因为你可能只想更新一个字段、两个字段或全部字段。若为每种字段组合都建独立 Input 类型会产生大量冗余只保留一个 Update Input 类型是开发者体验与灵活性的较好折中。另外注意Redwood 默认假设你的代码不会去设置id或createdAt字段因此将其排除在 Input 类型之外如果你的数据库允许手动设置这两个字段可以自行把它们加入CreateContactInput或UpdateContactInput。小技巧只读 SDL如果你只需要一个只读的 SDL例如只返回全部记录、不做增删改可以给 SDL 生成器加一个标志yarn rw g sdl Contact --no-crud这样只会生成一个contacts类型用于查询全部数据。第三步改造 SDL——公开创建、收回其他权限对于联系页我们只需要createContact。它接收唯一一个变量input即符合CreateContactInput形状的对象{ name, email, message }。这个 mutation 应允许任何人匿名提交因此把requireAuth改成skipAuth而返回全部联系人的contacts查询恰好应保持requireAuth——只有博客拥有者自己才能读取所有留言。同时删除更新与删除两个 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! skipAuth } 第四步Service 层——真正的业务逻辑Redwood 遵循简洁的命名约定SDL 文件api/src/graphql/contacts.sdl.{js,ts}中Query/Mutation类型里列出的每个字段都会映射到 Service 文件api/src/services/contacts/contacts.{js,ts}中同名的函数。生成出来的 Service 长这样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即便留在文件里也无妨——由于 SDL 中已没有对应字段客户端根本无法通过 GraphQL 调用它们。第五步用 GraphQL Playground 调试 API在正式接入 UI 之前先用 Redwood 自带的 GraphQL 图形界面验证 API 是否按预期工作。当你执行yarn redwood dev或简写yarn rw dev启动开发环境时实际上会同时启动两个进程Web 端与 API 端。另开一个浏览器标签页访问http://localhost:8911/graphql即可打开 GraphQL Yoga 内置的 GraphiQL——一个基于浏览器的 GraphQL GUI。页面右侧的 Docs 标签会展示由所有 SDL 文件合并成的完整 schema左侧编辑区支持自动补全提示点击 Play 按钮即可执行查询。例如可以查询数据库里所有帖子的id。遇到行为不符合预期的查询或 mutation 时Playground 也是绝佳的排错工具——它能让你先隔离 API 层本身的问题而不是在 Web 层与 API 层之间来回猜疑。第六步前端调用——定义 mutation 并用 useMutation 提交后端 mutation 已就绪现在在前端调用它。与表单相关的代码都在ContactPage中先把 mutation 定义为常量可以放在组件之外、紧跟import语句之后import { MetaTags, useMutation } from redwoodjs/web import { FieldError, Form, Label, TextField, TextAreaField, Submit, SubmitHandler, } from redwoodjs/forms import { CreateContactMutation, CreateContactMutationVariables, } from types/graphql const CREATE_CONTACT gql mutation CreateContactMutation($input: CreateContactInput!) { createContact(input: $input) { id } } interface FormValues { name: string email: string message: string } const ContactPage () { const [create] useMutation CreateContactMutation, CreateContactMutationVariables (CREATE_CONTACT) const onSubmit: SubmitHandlerFormValues (data) { console.log(data) } return ( MetaTags titleContact descriptionContact page / Form onSubmit{onSubmit} config{{ mode: onBlur }} Label namename errorClassNameerror Name /Label TextField namename validation{{ required: true }} errorClassNameerror / FieldError namename classNameerror / Label nameemail errorClassNameerror Email /Label TextField nameemail validation{{ required: true, pattern: { value: /^[^][^.]\..$/, message: Please enter a valid email address, }, }} errorClassNameerror / FieldError nameemail classNameerror / Label namemessage errorClassNameerror Message /Label TextAreaField namemessage validation{{ required: true }} errorClassNameerror / FieldError namemessage classNameerror / SubmitSave/Submit /Form / ) } export default ContactPage这里的CREATE_CONTACT引用了 Contacts SDL 中定义的createContactmutation传入一个input对象其中包含实际的 name、email、message 值。接着使用 Redwood 提供的useMutationhook记得从redwoodjs/web导入。它返回一个执行函数这里命名为create以及一组状态。create接收一个带variables键的对象variables内再放input键例如create({ variables: { input: { name: Rob, email: robredwoodjs.com, message: I love Redwood!, }, }, })巧的是Form会把所有字段组装成一个以字段名为键的对象传给onSubmit也就是说onSubmit收到的data对象本身就已经是input需要的格式直接透传即可const onSubmit: SubmitHandlerFormValues (data) { create({ variables: { input: data } }) }关于 TypeScript 自动生成的类型Redwood 会在 dev server 运行期间或执行yarn rw generate types时自动为 GraphQL 查询与 mutation 生成类型。一旦你定义了 GraphQL 层的CreateContactMutationRedwood 就会据此生成CreateContactMutation与CreateContactMutationVariables两个类型。更深入的说明参见 Generated Types。提交表单后数据库中就新增了一条 Contact 记录。你可以通过 Prisma Studio 或 GraphQL Playground 验证。关于默认安全的疑问之前提到未登录者不能查看所有联系人但目前还没有接入认证所以登录这个概念此刻并不存在。为了避免新应用在开发阶段频繁报错requireAuth在配置认证系统之前只是简单地返回true一旦配置了认证该指令就会用真实逻辑判断用户是否登录。第七步改进表单——三个体验问题现在联系表单可以工作了但它存在三个问题连续点击提交按钮会产生多次提交用户不知道提交是否成功若服务端出错用户得不到任何提示。逐一解决。提交期间禁用按钮useMutation除了返回执行函数外还返回一个包含多个状态的对象其中与本节相关的是loading与error可通过数组解构取得第二个元素const [create, { loading, error }] useMutation CreateContactMutation, CreateContactMutationVariables (CREATE_CONTACT)loading表示数据库调用是否仍在进行中把它赋给 Save 按钮的disabled属性即可防止重复提交Submit disabled{loading}Save/Submit开发环境本地提交速度很快肉眼几乎看不出差异可以在 Chrome DevTools 的 Network 面板里开启网络限速模拟慢网速就能看到 Save 按钮在等待响应的那一两秒内处于禁用状态。提交成功的 Toast 通知Redwood 内置了react-hot-toast可以快速弹出页面通知。useMutation的第二个参数是一个 options 对象其中包含回调函数onCompleted在 mutation 成功完成时触发。用它调用toast()函数弹出消息并把Toaster组件放进return中、Form之前import { toast, Toaster } from redwoodjs/web/toast const ContactPage () { const [create, { loading, error }] useMutation CreateContactMutation, CreateContactMutationVariables (CREATE_CONTACT, { onCompleted: () { toast.success(Thank you for your submission!) }, }) const onSubmit: SubmitHandlerFormValues (data) { create({ variables: { input: data } }) } return ( MetaTags titleContact descriptionContact page / Toaster / Form onSubmit{onSubmit} config{{ mode: onBlur }} {/* ... */} Submit disabled{loading}Save/Submit /Form / ) }Toast 通知的完整文档见 Toast Notifications。第八步服务端校验——用 Service Validations 兜底到目前为止表单只处理了客户端错误字段缺失或格式不正确。但如果服务端存在约束Form是无法感知的用户仍需要一个出错了的提示。客户端校验不能替代服务端校验——永远不要信任浏览器传来的数据。我们把邮箱校验也加进 API 侧确保即使有人绕过前端校验例如直接构造 GraphQL 请求坏数据也进不了数据库。Redwood 为此提供了 Service Validations即validate函数来自redwoodjs/apiimport type { QueryResolvers, MutationResolvers } from types/graphql import { validate } from redwoodjs/api export const createContact: MutationResolvers[createContact] ({ input }) { validate(input.email, email, { email: true }) return db.contact.create({ data: input }) }这一行里三个参数的含义分别是第一个参数要校验的值即input.email第二个参数对应页面上TextField的name用于把错误关联到具体输入框第三个参数校验指令对象email: true表示启用内置的邮箱格式校验器。当createContact被调用时会先校验输入只有没有任何校验抛出错误才会继续写库。validate 的源码实现validate定义在 packages/api/src/validations/validations.ts。它遍历你传入的校验指令对象逐一调用内置的 VALIDATORS 表export function validate( value: unknown, labelOrRecipe: string, recipe: ValidationRecipe, ): void { // ... for (const [validator, options] of Object.entries(validationRecipe)) { if (typeof options undefined) { continue } VALIDATORSvalidator as keyof typeof VALIDATORS } }内置邮箱校验器使用的正则极其宽松官方邮箱正则约有 6300 个字符这里取巧/^[^\s][^.\s]\.[^\s]$/含义是以若干非空白、非的字符开头 → 跟一个→ 跟若干非空白、非.的字符 → 跟一个.→ 以若干非空白字符结尾。若你有更严格的邮箱正则可以用format校验替代。为什么 name、email、message 的存在性无需手动校验原因有两点GraphQL 层已代为把关SDL 中Contact类型的字段声明为String!这意味着这些字段一到达 API 侧就不能为null否则 GraphQL 会拒绝请求并向客户端抛出错误数据库层也有兜底schema.prisma中这些字段被设为必填数据库本身会阻止任何null被写入。但要注意如果某个 Service 被另一个 Service 内部调用GraphQL 就不会介入校验。GraphQL 只在外部方如浏览器发起请求时参与。若你确实要保证某个字段必然存在或格式正确就必须把校验写进 Service 内部——这样无论谁调用该 ServiceGraphQL 或其他 Service数据都会先被检查。Redwood 的实践建议是数据格式属于业务逻辑的职责范围而业务逻辑应该放在 Services 里不要只依赖数据库做输入校验。用 FormError 展示服务端错误Form还有最后一个隐藏技巧FormError组件。把useMutation返回的error同时传给Form用于建立上下文和FormError用于渲染错误import { FieldError, Form, FormError, Label, TextField, TextAreaField, Submit, SubmitHandler, } from redwoodjs/forms // ... const ContactPage () { const [create, { loading, error }] useMutation CreateContactMutation, CreateContactMutationVariables (CREATE_CONTACT, { onCompleted: () { toast.success(Thank you for your submission!) }, }) return ( Toaster / Form onSubmit{onSubmit} config{{ mode: onBlur }} error{error} FormError error{error} wrapperClassNameform-error / {/* ...表单字段... */} Submit disabled{loading}Save/Submit /Form / ) }为验证服务端校验生效可以临时把TextField nameemail中validation的pattern部分移除让非法邮箱绕过前端校验直达服务端TextField nameemail validation{{ required: true, - pattern: { - value: /^[^][^.]\..$/, - message: Please enter a valid email address, - }, }} errorClassNameerror /提交一个非法邮箱后页面顶部会出现一行通俗易懂的错误概要同时出错的字段也会像行内校验一样被高亮。顶部的错误汇总框对短表单可能略显冗余但对多屏长表单价值巨大——用户可以在一个地方看到所有错误摘要不必在长长的表单里逐个寻找红框。如果不想用顶部的汇总框移除FormError即可字段高亮仍然生效。FormError提供了多组样式选项分别作用于消息的不同部分wrapperStyle/wrapperClassName整条消息的容器titleStyle/titleClassNameErrors prevented this form... 标题listStyle/listClassName承载错误列表的ullistItemStyle/listItemClassName每条错误所在的li。Service Validations 的更多玩法Service Validations 远不止邮箱校验。可以在一次调用中组合多个指令也可以叠加多条validate调用。假设有一个代表汽车的Car模型用户提交二手车信息到专属汽车商城可以非常挑剔地限定可提交的值全程只用内置validate()调用、无需任何自定义检查export const createCar ({ input }: Car) { 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 }) }从源码看内置校验器包括absence字段必须为空、acceptance值必须为 true 或在允许列表中、email邮箱格式、exclusion值不得在列表中可配caseSensitive、format匹配正则可传pattern、inclusion值必须在列表中、lengthmin/max/equal/between、numericality数值性支持integer、lessThan、lessThanOrEqual、greaterThan、greaterThanOrEqual、equal、otherThan、even、odd、positive、negative、presence字段必须存在支持allowNull、allowUndefined、allowEmptyString。每个校验都支持message选项自定义错误文案。还可以用validateWith跑自定义校验逻辑抛出的错误会以与内置校验相同的方式被处理成服务端校验错误并回传给客户端GraphQL 会吞掉普通异常只回一句Something went wrongvalidateWith会把真实错误信息转成ServiceValidationError透传validateWith(() { const oneWeekAgo new Date() oneWeekAgo.setDate(oneWeekAgo.getDate() - 7) if (input.lastCarWashDate oneWeekAgo) { throw new Error(We dont accept dirty cars) } })源码中还有validateUniqueness工具它在数据库事务中先检查某字段的唯一性支持$self排除当前记录、$scope限定范围再执行回调用于用户名/邮箱不能重复这类场景可参见 validations.ts。第九步提交成功后重置表单我们没有在提交后做页面跳转因此至少应该清空表单字段。这需要调用 React Hook Form 的reset()但Form的基础用法我们当前的用法并不暴露它。Redwood 的Form内部默认会调用 React Hook Form 的useForm()为了拿到reset()我们需要自己调用一次useForm()并把返回的方法对象传给Form的formMethodsprop让Form使用我们提供的实例而不是自建。首先导入useFormimport { FieldError, Form, FormError, Label, Submit, TextAreaField, TextField, useForm, } from redwoodjs/forms在组件内调用const ContactPage () { const formMethods useForm() // ... }把formMethods传给FormForm onSubmit{onSubmit} config{{ mode: onBlur }} error{error} formMethods{formMethods} 然后在onCompleted回调中、toast()之后调用formMethods.reset()const [create, { loading, error }] useMutation CreateContactMutation, CreateContactMutationVariables (CREATE_CONTACT, { onCompleted: () { toast.success(Thank you for your submission!) formMethods.reset() }, })注意一个细节一旦自己调用useForm()原本由 Redwood 自动注入的config就不再生效——Redwood 之前是在内部替你调用useForm()并自动把Form上的configprop 传进去。现在useForm()由你自己调用若需要类似onBlur的校验模式就得手动传入const formMethods useForm({ mode: onBlur })别忘了把邮箱的正则校验加回TextField的validation中——不过服务端校验应保留以防万一。完整页面代码经过以上全部步骤ContactPage的完整代码TypeScript 版如下import { MetaTags, useMutation } from redwoodjs/web import { toast, Toaster } from redwoodjs/web/toast import { FieldError, Form, FormError, Label, Submit, SubmitHandler, TextAreaField, TextField, useForm, } from redwoodjs/forms import { CreateContactMutation, CreateContactMutationVariables, } from types/graphql const CREATE_CONTACT gql mutation CreateContactMutation($input: CreateContactInput!) { createContact(input: $input) { id } } interface FormValues { name: string email: string message: string } const ContactPage () { const formMethods useForm({ mode: onBlur }) const [create, { loading, error }] useMutation CreateContactMutation, CreateContactMutationVariables (CREATE_CONTACT, { onCompleted: () { toast.success(Thank you for your submission!) formMethods.reset() }, }) const onSubmit: SubmitHandlerFormValues (data) { create({ variables: { input: data } }) } return ( MetaTags titleContact descriptionContact page / Toaster / Form onSubmit{onSubmit} config{{ mode: onBlur }} error{error} formMethods{formMethods} FormError error{error} wrapperClassNameform-error / Label namename errorClassNameerror Name /Label TextField namename validation{{ required: true }} errorClassNameerror / FieldError namename classNameerror / Label nameemail errorClassNameerror Email /Label TextField nameemail validation{{ required: true, pattern: { value: /^[^][^.]\..$/, message: Please enter a valid email address, }, }} errorClassNameerror / FieldError nameemail classNameerror / Label namemessage errorClassNameerror Message /Label TextAreaField namemessage validation{{ required: true }} errorClassNameerror / FieldError namemessage classNameerror / Submit disabled{loading}Save/Submit /Form / ) } export default ContactPageReact Hook Form 提供了大量Form未直接暴露的功能完整 API 可查阅其官方文档。当需要这些能力时自己调用useForm()即可但务必把返回值如这里的formMethods作为 prop 传给Form保证校验与其他既有功能继续正常工作。相关组件的实现可在 packages/forms/src/Form.tsx 中查看formMethods与config正是它对外暴露的两个关键 props。小结至此联系我们这一完整的数据保存链路已经打通Prisma 模型 → 迁移 → SDL/Service → GraphQL Playground 验证 → 前端 useMutation 提交 → loading 防重 → Toast 通知 → 服务端校验 → 表单重置。下一步教程将把博客后台的创建/编辑功能迁移到一个受登录保护的 admin 区域让普通用户无法通过随意构造 URL 来发布内容——那正是认证与授权章节的内容。【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考