从 Graphcool Framework 迁移到 Prisma：双层 GraphQL 架构转型实战指南

后端数据库GraphQL【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址https://gitcode.com/gh_mirrors/pr/prisma1点击查看免费下载本文是 Graphcool to Prisma 升级指南 的入门总览面向使用过 Graphcool FrameworkGraphcool 前 Backend-as-a-Service 的开源版本的开发者。文章梳理了 Prisma 与 Graphcool Framework 的本质差异讲解数据库层 应用层双层 GraphQL 架构的核心理念并给出数据迁移、认证授权迁移、函数迁移与部署方式转型的完整路线。读完本文你将掌握把 Graphcool 服务迁移到 Prisma 的整体思路、主要 API 变更清单以及各专项迁移的操作入口。理解前提GraphQL 与 Graphcool 的历史背景在动手迁移之前首先需要明确三者的关系Graphcool Framework是 Graphcool 公司早先 Backend-as-a-Service 产品的开源版本它提供了一套意见化opinionated的 GraphQL 后端搭建方案开发者几乎不需要编写服务端代码即可获得一个可用的 GraphQL API。Prisma是一个 GraphQL 查询引擎GraphQL query engine它同时也是驱动 Graphcool Framework 运行的核心底层技术。两者的定位差异在于Graphcool Framework 帮你做了大量架构决策、屏蔽了许多实现细节而 Prisma 只负责数据库层的通用 CRUD GraphQL API把业务层的决策权完全交还给开发者。由于 Prisma 的本质是一个位于数据库之上的 GraphQL 查询引擎在迁移前你必须对以下概念有扎实理解否则无法真正理解 Prisma 提供的价值GraphQL schema类型系统与字段定义的契约root typesQuery、Mutation、Subscription三类根类型resolver functions每个字段的实际解析函数。如果你此前使用 Graphcool 托管 GraphQL 服务建议先补齐上述概念再开始阅读本文与后续的 数据建模与 GraphQL API 迁移、认证与授权迁移 等章节。迁移前的准备先在开发环境演练官方推荐的迁移策略是先在开发环境中完整走一遍迁移流程再部署到生产环境以此保证迁移过程平滑可控。数据本身的迁移可以复用 Graphcool/Prisma 服务通用的import导入与 export导出功能在两个项目之间搬运数据。具体的导入导出命令与数据格式说明参见 Data Import Export 参考章节。基本流程是从旧 Graphcool 服务中导出数据在开发环境新建 Prisma 服务并导入数据验证数据完整性与 API 行为确认无误后再对生产环境执行同样的操作。新架构你的 GraphQL 服务器把 Prisma 作为数据库层迁移到 Prisma 后最核心的架构变化是GraphQL 服务器由单层变为两个 GraphQL 层数据库层database layer由 Prisma 提供是整个服务器的核心。它暴露的 GraphQL API 本质上是 Graphcool 中Simple API与Relay API的合并增强版为数据模型中定义的每个类型提供通用且强大的 CRUD 操作。应用层application layer对只使用过 Graphcool Framework 的开发者来说这是一个全新概念。它定义面向客户端应用程序的另一个 GraphQL API完全按业务需求定制——查询字段、变更操作、返回类型都服务于具体应用场景。在这个新架构中业务逻辑由应用层全权负责包括认证authentication、权限permissions、文件处理file handling等常见工作流。与 Graphcool Framework 时期编写 Resolver 或 Hook 函数不同你现在只需要实现传统的 GraphQL resolver。应用层实现 resolver 的开销非常小因为进入的请求可以简单地**委托delegate**给底层 Prisma API。这正是prisma-binding包的核心作用——它像一个为 Prisma 服务自动生成的 SDK让大多数 resolver 退化为一行代码。典型实现形如Query: { posts(parent, args, ctx, info) { return ctx.db.query.posts({}, info) }, post(parent, args, ctx, info) { return ctx.db.query.post({ where: { id: args.id } }, info) }, },关于prisma-binding的完整使用方式动态绑定与静态绑定、代码生成等参见 Prisma Bindings 参考文档。数据建模与 GraphQL API 的主要变更迁移过程中你的数据模型data model写法与生成的 GraphQL API 都会发生一系列变化具体清单详见 Data Modelling GraphQL API 迁移文档。这里提炼最核心的几点数据模型层面的变更移除model指令Graphcool 中用于标记模型类型的model指令被删除。例如type User model { ... }直接写成type User { ... }。relation指令在关系唯一时变为可选当数据模型中的关系不存在歧义时可以省略relation(name: ...)。id字段变为可选与createdAt、updatedAt类似id不再是模型类型上的必填字段不需要时可以删除。指令重命名isUnique更名为uniquedefaultValue(value: ...)更名为default(value: ...)。GraphQL API 层面的变更统一 APIPrisma 合并了原先的 Simple API 与 Relay API合并后的 API 兼容所有 GraphQL 客户端因此每个 Prisma 服务只提供一个 HTTP endpoint。变更参数包裹进data原先直接传单值给 mutation现在所有输入参数都包裹在一个data参数中# Before mutation { createPost(title: GraphQL is great text: It really is) { id } } # After mutation { createPost(data: { title: GraphQL is great text: It really is }) { id } }查询根字段去掉all-前缀allUsers变为users查询单个节点的根字段改为小写User(id: ...)变为user(id: ...)。filter更名为where列表查询的过滤参数由filter改为where例如allUsers(filter: { name_contains: Karl })对应users(where: { name_contains: Karl })。支持按任意unique字段选择节点Graphcool 时期只能通过id更新/删除节点Prisma 允许使用任意标注了unique的字段例如deleteUser(by: { email: alicegraph.cool })。新增 API 原语Prisma 还引入了批量操作batch operations、增强的嵌套变更nested mutations、事务性变更transactional mutations等新特性许多以前需要复杂方案实现的使用场景现在可以直接用这些原语完成。认证与授权从权限查询到应用层校验Graphcool Framework 通过扩展 schema 的Mutation类型定义signup、login类 resolver 函数实现认证并用权限查询permission queries规则来控制每次 API 操作。迁移到 Prisma 后这套机制发生根本性变化Prisma 自身只提供简单的基于 token类似 API Key的 Prisma API 访问控制不再绑定任何权限系统用户认证与权限规则全部下沉到应用层实现JWT token 由你自己生成不再是graphcool-lib生成prisma-binding包提供的exists函数可以扮演 Graphcool 权限查询的类似角色例如在updatePostresolver 中校验当前请求者是否为该帖作者const requestingUserIsAuthor await ctx.db.exists.Post({ id, author: { id: userId }, }) if (requestingUserIsAuthor) { return await ctx.db.mutation.updatePost({ where: { id }, data: { title, text } }, info) } throw new Error(Invalid permissions, you must be an admin or the author of a post to update it)完整的 schema 迁移、resolver 迁移与getUserId工具函数实现参见 Authentication Authorization 迁移文档。函数迁移hooks、resolvers 与 subscriptionsGraphcool Framework 中的三类服务端函数在 Prisma 中均有对应的迁移方案详见 Functions 迁移文档Hooks数据校验与转换原先在 mutation 执行前挂接的 hook 函数现在把校验/转换逻辑直接搬进应用层对应 resolver 内部例如在createUserresolver 中先检查name.length 2再委托给ctx.db.mutation.createUser。Resolver 函数扩展 CRUD API、对接第三方服务原来由SDL schema 扩展 JavaScript 实现 服务定义文件关联三部分构成现在 schema 扩展直接进入应用层 schema实现变成 GraphQL 服务器中普通的 resolver 函数。服务端订阅Server-side subscriptionsPrisma 不再支持托管函数managed functions订阅的 handler 只能通过webhook配置指向你自己部署的 HTTP 端点如 AWS Lambda、Google Cloud Functions、Zeit Now。配置从 Graphcool 的functions:块变为 Prisma 的subscriptions:块subscriptions: createFirstArticle: query: src/createFirstArticle.graphql webhook: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev/createFirstArticle此外文件处理File Handling的迁移方案单独成篇参见 File Handling 迁移文档。部署从托管服务到自运维与 Graphcool Framework 相比Prisma 的另一个重大差异是你需要自行负责 GraphQL 服务器的部署。可选方案包括Zeit Now 一键部署官方推荐的便捷选项之一up工具Apex 出品的部署工具任意云厂商Prisma 服务运行在 Docker 上可以部署到 Digital Ocean、AWS 等任何云平台Prisma Cloud基于 Prisma Cloud 的托管部署选项。部署细节与各环境的配置方式参见 Server Hosting 迁移文档。迁移路线总览综合整个升级指南一次完整的 Graphcool → Prisma 迁移按如下顺序推进理解架构差异确认双层 GraphQL 架构本文迁移数据模型与 API按 Data Modelling GraphQL API 的清单改写数据模型、更新客户端查询迁移认证与授权在应用层实现 signup/login 与权限校验Authentication Authorization迁移服务端函数把 hooks/resolvers 搬进应用层 resolver把订阅改为 webhookFunctions迁移文件处理逻辑File Handling规划部署在开发环境验证后用 Docker/云厂商/Prisma Cloud 完成生产部署Server Hosting。整个过程中务必坚持先在开发环境演练、再上生产的原则并善用 import/export 机制完成数据迁移即可把迁移风险控制在最小范围。赞分享后端数据库GraphQL【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址https://gitcode.com/gh_mirrors/pr/prisma1点击查看免费下载相关推荐3个场景告诉你为什么你的macOS文件预览需要这些神器插件3个场景告诉你为什么你的macOS文件预览需要这些神器插件 你是否曾经在Finder中选中一个文件满怀期待地按下空格键结果看到的却是无法预览或是一堆后端数据库GraphQLGraphcool 到 Prisma 迁移指南从 Graphcool Framework 过渡到 Prisma 的双层 GraphQL 架构Graphcool 到 Prisma 迁移指南从 Graphcool Framework 过渡到 Prisma 的双层 GraphQL 架构 导读 本文以 P后端数据库GraphQL从 Graphcool Framework 迁移到 Prisma 1.x两层 GraphQL 架构迁移完整指南从 Graphcool Framework 迁移到 Prisma 1.x两层 GraphQL 架构迁移完整指南 导读 本文基于本仓库 docs/1.1/04后端数据库GraphQL上一篇EspoCRM邮件功能优化群组文件夹自动添加团队成员权限下一篇HyperMD 快速入门指南打造现代化 Markdown 编辑器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考