从 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 Framework（Graphcool 前 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 types：Query、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更名为@unique；@defaultValue(value: "...")更名为@default(value: "...")。

GraphQL API 层面的变更

统一 API：Prisma 合并了原先的 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: "alice@graph.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 与 subscriptions

Graphcool 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 subscriptions）：Prisma 不再支持托管函数（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 迁移文档。