★ FEATURED ARTICLE 后端数据库GraphQL【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址https://gitcode.com/gh_mirrors/pr/prisma1点击查看免费下载导读本文是 Prisma API 中Mutations变更操作的完整技术指南讲解如何通过 GraphQL 端点修改数据。你将掌握四类核心能力单节点对象变更create / update / upsert / delete、跨关系的嵌套变更connect / disconnect / create / update / upsert / delete、标量列表scalar list字段的 set 操作以及批量更新/删除updateMany / deleteMany。文中所有示例基于一个User与Post的数据模型并结合当前仓库 SchemaBuilder.scala 的源码说明这些 mutation 字段是如何从数据模型自动生成并执行的帮助你既会用也理解为何如此设计。前置知识Mutations 从何而来Prisma API 是围绕服务的数据模型data model自动生成的数据模型用 SDL 写在.graphql文件中典型命名为datamodel.graphql在prisma.yml的datamodel属性中声明见 Data Modelling (SDL).md)Prisma 据此生成底层的数据库 schema再对外暴露一套 GraphQL schema其中Mutation根类型就是全部变更操作的入口。从源码看API schema 的构建位于 SchemaBuilder.scaladef buildMutation(): Option[ObjectType[ApiUserContext, Unit]] { val fields project.nonEmbeddedModels.map(createItemField) project.nonEmbeddedModels.flatMap(updateItemField) project.nonEmbeddedModels.flatMap(deleteItemField) project.nonEmbeddedModels.flatMap(upsertItemField) project.nonEmbeddedModels.flatMap(updateManyField) project.nonEmbeddedModels.map(deleteManyField) rawAccessField Some(ObjectType(Mutation, fields)) }可见每个非嵌入式non-embedded模型都会自动获得createModel、updateModel、deleteModel、upsertModel、updateManyModels、deleteManyModels等字段名称规则即create/update/upsert/delete 模型名批量操作用复数模型名例如updateManyPosts。每个字段在解析时都会构造对应的Create、Update、Delete、Upsert、UpdateMany、DeleteMany执行对象并通过ClientMutationRunner.run(...)交给数据库 mutaction 执行器落地。本文后续所有示例都基于如下数据模型type Post { id: ID! unique title: String! published: Boolean! author: User! } type User { id: ID! unique age: Int email: String! unique name: String! posts: [Post!]! }提示部署服务后在服务工作目录运行prisma playground或将服务 HTTP endpoint 粘贴到浏览器地址栏见 Overview即可在 GraphQL Playground 中交互式探索你的 Prisma API 中实际生成的 mutations。Object mutations单节点对象变更模型变更model mutations用于修改某个模型的单个节点包括创建、更新、upsert 与删除四种。创建节点create使用createUser创建一个新用户# Create a new user mutation { createUser( data: { age: 42 email: zeusexample.com name: Zeus } ) { id name } }注意data输入对象中所有没有默认值的必填字段都必须显式给出默认值机制见 Data Modelling (SDL).md)。createItemField的实现SchemaBuilder.scala会为模型生成字段名create${model.name}并用argumentsBuilder.getSangriaArgumentsForCreate(model)生成data参数——data的类型即该模型对应的 create 输入类型。更新节点update使用updateUser修改email和name。注意这里通过where参数[选择要更新的节点]node selection见 Conceptsmutation { updateUser( data: { email: zeus2example.com name: Zeus2 } where: { email: zeusexample.com } ) { id name } }where的取值来自带unique指令的字段本例用email也可以用id。updateItemFieldSchemaBuilder.scala返回Option[Field]字段名update${model.name}返回类型为OptionType(objectTypes(model.name))——即更新一个不存在的节点时返回null。Upsert 节点upsert如果希望在一个 mutation 里完成存在则更新、不存在则创建使用 upsert# Upsert a user mutation { upsertUser( where: { email: zeusexample.com } create: { email: zeusexample.com age: 42 name: Zeus } update: { name: Another Zeus } ) { name } }注意create和update的类型分别与createUser/updateUser中的data对象一致。源码中upsertItemFieldSchemaBuilder.scala字段名为upsert${model.name}解析时构造Upsertmutation 对象执行。删除节点delete删除节点同样通过where选择要删除的节点。按id删除mutation { deleteUser(where: { id: cjcdi63l20adx0146vg20j1ck }) { id name email } }因为email也标注了unique所以同样可以用email选择并删除User节点mutation { deleteUser(where: { email: cjcdi63l20adx0146vg20j1ck }) { id name email } }Nested mutations跨关系的嵌套变更create和update模型变更可以在同一时间修改跨关系的节点这被称为嵌套变更nested mutations并且是事务性执行的transactionally见 Concepts 中关于事务性变更的说明——即要么全部成功要么全部回滚。可用参数总览嵌套变更共有以下参数createupdateupsertdeleteconnectdisconnect它们的可用性与具体行为取决于两个因素父 mutation 的类型create mutation / update mutation / upsert mutation关系的类型可选 to-one 关系 / 必填 to-one 关系 / to-many 关系。例如create mutation 只暴露嵌套的create和connectupdate mutation 对必填的 to-one 关系暴露update、upsert等。建议不必在此穷举所有组合推荐用 GraphQL Playground 实际探索不同嵌套 mutation 的行为。从源码结构看嵌套参数的解析与展开位于 NestedMutations.scala而仓库测试中提供了大量对应场景的验证用例例如 NestedConnectMutationInsideCreateSpec.scala、NestedCreateMutationInsideCreateSpec.scala、NestedDeleteMutationInsideUpdateSpec.scala、NestedDisconnectMutationInsideUpdateSpec.scala可用于印证每种嵌套操作的参数形态。示例创建并连接相关节点在嵌套输入对象字段中使用connect可以连接到已有的一个或多个相关节点。下面创建一个新的Post并通过唯一的email字段connect到已存在的author——此时connect提供了一种节点选择方式# Create a post and connect it to an author mutation { createPost(data: { title: This is a draft published: false author: { connect: { email: zeusexample.com } } }) { id author { name } } }如果在author中提供create参数而不是connect则会创建一个相关author并同时连接它而不是连接已存在的 author。由于User对Post是 to-many 关系创建User时可以同时create和connect多个Post节点。下面创建一个新User同时创建两个新Post并连接两个已存在的Post# Create a user, create and connect new posts, and connect to existing posts mutation { createUser( data: { email: zeusexample.com name: Zeus age: 42 posts: { create: [{ published: true title: First blog post }, { published: true title: Second blog post }] connect: [{ id: cjcdi63j80adw0146z7r59bn5 }, { id: cjcdi63l80ady014658ud1u02 }] } } ) { id posts { id } } }示例更新与 upsert 相关节点更新节点时可以同时更新一个或多个相关节点。注意update接受一个对象列表每个对象包含适合updatePostmutation 的where与data字段mutation { updateUser( data: { posts: { update: [{ where: { id: cjcf1cj0r017z014605713ym0 } data: { title: Hello World } }] } } where: { id: cjcf1cj0c017y01461c6enbfe } ) { id } }嵌套 upsert 的工作方式类似mutation { updatePost( where: { id: cjcf1cj0r017z014605713ym0 } data: { author: { upsert: { where: { id: cjcf1cj0c017y01461c6enbfe } update: { email: zeus2example.com name: Zeus2 } create: { email: zeusexample.com name: Zeus } } } } ) { id } }示例删除相关节点更新节点时可以同时删除一个或多个相关节点此时delete同样提供节点选择能力mutation { updateUser( data: { posts: { delete: [{ id: cjcf1cj0u01800146jii8h8ch }, { id: cjcf1cj0u01810146m84cnt34 }] } } where: { id: cjcf1cj0c017y01461c6enbfe } ) { id } }Scalar list mutations标量列表变更当对象类型object type的某个字段是**标量列表scalar list**类型时会有一组特殊的 mutation 可用。考虑以下User类型它有三个标量列表字段type User { id: ID! unique scores: [Int!]! # scalar list for integers friends: [String!]! # scalar list for strings coinFlips: [Boolean!]! # scalar list for booleans }注原文档示例中存在一个笔误——throws并非上方数据模型中的字段实际应为coinFlips。创建节点时设置标量列表创建新User节点时可以用set为每个标量列表字段提供值列表mutation { createUser(data: { scores: { set: [1, 2, 3] } friends: { set: [Sarah, Jane] } coinFlips: { set: [false, false] } }) { id } }更新节点时的标量列表操作更新已有User节点时对标量列表字段有若干附加操作set用全新的列表覆盖现有列表push即将推出在列表任意位置添加一个或多个元素pop即将推出从列表开头或末尾移除一个或多个元素remove即将推出移除所有匹配给定过滤条件的元素。注意push、pop和remove在当前版本尚未实现。如果想预览它们未来的形态可以查看对应的 prisma/issues/1275 规格讨论。set详解在updatemutation 中每个标量列表字段接受一个含set字段的对象set的值可以是单个标量值或对应标量类型的列表。将某个已有User的scores设为[1]注意这里传的是单个值1mutation { updateUser( where: { id: cjd4lfdyww0h00144zst9alur } data: { scores: { set: 1 } } ) { id } }将scores设为[10, 20, 30]mutation { updateUser( where: { id: cjd4lfdyww0h00144zst9alur } data: { scores: { set: [10,20,30] } } ) { id } }仓库中的 DeleteScalarListsSpec.scala 与 UpdateManyListSpec.scala 等测试用例覆盖了标量列表字段的删除与批量更新场景可作为行为参考。Batch mutations批量变更批量 mutation 用于一次更新或删除大量节点返回数据只包含受影响节点的count。更新多个节点用where选择受影响节点支持各种过滤条件见 Concepts 中的 batch operations用data指定新值所有节点会被更新为相同值。注意批量 mutation不会触发任何 subscription 事件发布所有创建于 2017 年且未发布的Post节点利用createdAt_gte/createdAt_lt时间过滤与published: false条件mutation { updateManyPosts( where: { createdAt_gte: 2017 createdAt_lt: 2018 published: false } data: { published: true } ) { count } }删除某位author的所有未发布Postauthor内联对象提供关系过滤mutation { deleteManyPosts( where: { published: false author: { name: Zeus } } ) { count } }从源码看批量字段名使用复数模型名pluralsCache.pluralName(model)如updateManyPosts/deleteManyPosts返回类型为objectTypeBuilder.batchPayloadType即包含count的批量载荷类型见 SchemaBuilder.scala。批量过滤参数的构建在 ArgumentsBuilder 与 InputTypesBuilder.scala 中完成。仓库对应测试包括 UpdateManySpec.scala、UpdateManyRelationFilterSpec.scala、DeleteManySpec.scala 与 DeleteManyMutationRelationsSpec.scala覆盖了批量更新/删除及关系过滤的行为验证。总结与实践建议按操作类型选用 mutation单个节点用createModel/updateModel/upsertModel/deleteModel大批量变更用updateManyModels/deleteManyModels只返回count且不触发订阅事件跨关系操作使用嵌套 mutation 参数create、update、upsert、delete、connect、disconnect并注意不同父 mutation 与关系类型下可用参数的差异。利用unique字段做节点选择where参数可接受id或任何带unique指令的字段如email这与 Concepts 中描述的节点选择机制一致。依赖事务保证嵌套 mutations 事务性执行适合要么全成功、要么全失败的跨关系写入。用 Playground 验证部署后通过prisma playground打开 GraphQL Playground查看服务实际生成的 mutation 字段与输入类型这是探索嵌套组合与标量列表操作的最快方式。注意版本差异标量列表的push/pop/remove尚未实现目前仅有set可用本文内容基于仓库中docs/1.4文档版本对应的 Prisma API 行为。赞分享后端数据库GraphQL【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址https://gitcode.com/gh_mirrors/pr/prisma1点击查看免费下载相关推荐Prisma API Mutations 完全指南模型变更、嵌套关系操作与批量更新Prisma API Mutations 完全指南模型变更、嵌套关系操作与批量更新 Prisma 服务会自动基于其数据模型生成一套完整的 GraphQL AP后端数据库GraphQLPrisma 1 Mutations 权威指南创建、更新、Upsert、删除与嵌套/批量变更全解析Prisma 1 Mutations 权威指南创建、更新、Upsert、删除与嵌套/批量变更全解析 Prisma 1 的 GraphQL API 提供了一整套后端数据库GraphQLPrisma API 变更操作Mutations完整指南对象、嵌套、标量列表与批量变更实战Prisma API 变更操作Mutations完整指南对象、嵌套、标量列表与批量变更实战 本文围绕 Prisma 1.x 服务自动生成的 GraphQL后端数据库GraphQL上一篇如何免费快速生成专业 PDF 发票Invoify 在线发票生成器完整指南下一篇深入理解Goldmark AST架构轻松掌握Markdown文档的内部表示创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
