Prisma 入门实战：使用 CLI 从零为数据库生成可调用的 GraphQL API

后端数据库GraphQL【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址https://gitcode.com/gh_mirrors/pr/prisma1点击查看免费下载本篇技术指南以 Prisma 1本仓库即 prisma1 的镜像架构说明为核心完整演示从安装 Prisma CLI、用prisma init引导一个最小服务、编写prisma.yml与数据模型、prisma deploy部署到在 GraphQL Playground 中发送查询Query与变更Mutation的全流程。读完本文你将掌握数据模型 → 部署 → 自动生成 CRUD API这一核心工作流并能独立在自己的项目里复刻出可调用的 GraphQL 后端。安装 Prisma CLIPrisma 服务统一由 Prisma CLI 管理。它负责引导服务脚手架、解析prisma.yml、执行部署、打开 Playground 以及生成客户端等一系列操作。打开终端执行以下任一命令即可全局安装npm install -g prisma # 或者使用 yarn # yarn global add prisma本仓库构建的 CLI 二进制在源码提示文本中写作prisma1例如 deploy.ts 的帮助文本 中出现的$ prisma1 deploy对应 Prisma 1 系列教程中的命令统一写作prisma。若你使用本仓库自行构建的版本可将下文命令中的prisma替换为prisma1。用prisma init引导一个 Prisma 服务进入任意目录执行引导命令prisma init hello-world该命令会在当前目录下创建名为hello-world的新目录并生成两个提供最小服务骨架的文件prisma.yml服务的根配置文件。它包含服务名用于生成服务的 HTTP 端点、用于保护端点的密钥secret以及服务应部署到何处等信息。datamodel.graphql也可以命名为其他名字如types.graphql用 GraphQL SDL 编写的数据模型定义文件。补充说明hello-world目录中其实还有第三个文件.graphqlconfig.yml。它遵循基于graphql-config的行业标准来配置和结构化 GraphQL 项目。一旦存在它就会被 GraphQL 工具链如 GraphQL Playground、graphql-cli、文本编辑器、构建工具等读取用于改进本地开发工作流。从源码看prisma init在 init.ts 中实现它有两点值得注意它接收可选的目录名参数dirName也支持--endpoint-e参数直接指定初始服务端点跳过交互式提问如果目标目录已存在prisma.yml或datamodel.prisma命令会报错并提示更换目录名或删除冲突文件init.ts避免覆盖已有配置。生成的prisma.yml与属性说明教程生成的prisma.yml内容如下service: hello-world stage: dev datamodel: datamodel.graphql # to enable auth, provide # secret: my-secret disableAuth: true各属性的含义属性说明service服务名是服务 HTTP 端点的一部分。在 PrismaDefinition.ts 中它最终会同stage、workspace一起拼接成完整的getApiEndpoint(serviceName, stageName, workspace)端点地址见 deploy.ts 的 printEndpoints。stage同一个服务可以部署到多个阶段stage例如一个dev开发环境和一个prod生产环境用于隔离不同环境下的同一套服务定义。datamodel指向包含数据模型定义文件的路径。prisma deploy会把该文件中解析出的类型字符串typesString连同其他配置一起提交给部署接口deploy.ts。disableAuth若为true任何知道服务端点的人都能对 API 进行完全读写。若为false则必须在prisma.yml中指定secret用它生成 JWT 认证令牌调用 API 时需在请求的Authorization头中携带该令牌。获取令牌最方便的方式是 CLI 的prisma token命令。注意本教程全程保持disableAuth: true。在生产应用中务必为服务启用认证从源码看secret支持逗号分隔的多个密钥解析逻辑secrets.replace(/\s/g, ).split(,)位于 PrismaDefinition.ts生成令牌的命令实现在 token/token.ts它还支持--copy-c参数直接把令牌复制到系统剪贴板。datamodel.graphql数据模型是 API 的基石教程生成的datamodel.graphql内容如下type User { id: ID! unique name: String! }数据模型包含应用领域内各实体的类型定义。这里是最简单的User类型只有id和name两个字段。unique指令表示数据库里不可能存在两个id相同的用户Prisma 会在任何时候保证这一约束成立。版本差异提示教程对应的 1.1 文档时期使用unique声明id的唯一性而在当前仓库的 init 脚手架模板中主键改用id指令声明——见 boilerplate/datamodel.prismaid: ID! idMongoDB 场景的模板 datamodel-mongo.prisma 与之相同。id负责标记主键unique仍可用于其他唯一字段两者都向 Prisma 声明了唯一性约束。部署服务prisma deployprisma.yml和datamodel.graphql只是抽象的服务定义。要让服务真正运行起来、能通过 HTTP 被调用必须执行部署。在hello-world目录内运行prisma deploy由于此时prisma.yml还不包含部署到哪里即部署到哪个cluster的信息CLI 会弹出交互式提问。此时你可以二选一本地部署使用 Docker 运行 Prisma 服务前提是本机已安装 Docker部署到公共 Prisma 集群本教程选择公共集群。当被问到要部署到哪个cluster时选择公共集群选项prisma-eu1或prisma-us1。至此你的 Prisma 服务已部署完成可以接受查询queries与变更mutations了。deploy命令的源码视角从 deploy/deploy.ts 可以看到部署流程的内部细节部署前会先通过definition.load加载prisma.yml若其中缺少datamodel属性会直接报错终止deploy.ts若prisma.yml中没有service/stage或显式传入--new-n参数就会进入EndpointDialog交互式选择集群选择结果会被写回prisma.ymldeploy.ts部署本质是一次数据模型迁移CLI 调用服务端deploy接口拿到迁移步骤migration.steps随后轮询迁移状态直至SUCCESS再按需执行post-deployhooks 与首次部署的 seeddeploy.ts成功后命令会打印 HTTP 与 WebSocketWS两个端点地址其中 WS 端点用于 GraphQL 订阅printEndpoints。prisma deploy还支持若干实用参数方便在真实项目中控制部署行为参数说明--force/-f接受因 schema 变更可能导致的数据丢失忽略警告继续部署--new/-n强制进入交互模式重新选择集群--dry-run/-d只做一次部署预演不真正执行--no-seed首次部署服务时禁用 seed 数据--json/-j以 JSON 格式输出--no-migrate禁用迁移需要 Prisma 1.26 及以上版本的服务端--no-generate禁用部署后的隐式客户端生成--skip-hooks禁用部署触发的 hooks--env-file/-e指定注入环境变量的.env文件路径--project/-p指定 Prisma 定义文件prisma.yml路径在 GraphQL Playground 中探索 API服务已经部署好了但如何知道它的 API 长什么样、如何与之交互呢总的来说生成的 API 允许对数据模型中的类型执行 CRUD 操作同时还暴露 GraphQL订阅subscriptions——客户端可以订阅某些事件实时收到更新。要特别理解的是数据模型是 API 的基础每次修改数据模型GraphQL API 都会随之更新。由于数据模型中包含User类型Prisma API 现在允许客户端创建、读取、更新、删除该类型的实例即节点。具体而言基于User类型会生成以下 GraphQL 操作user按id或其他unique字段查询单个User节点users查询User节点列表createUser创建新User节点的变更updateUser更新已有User节点的变更deleteUser删除已有User节点的变更。注意上述列表并非完整。Prisma API 还暴露了更多便捷操作例如批量更新/删除多个节点。但所有操作本质上都是对数据模型中所定义类型的节点进行创建、读取、更新或删除。要实际使用这些操作你需要一种向服务 API 发送请求的方式。由于 API 通过 HTTP 暴露理论上可以用curl、Postman 之类的工具交互但 GraphQL 生态提供了更顺手的工具——GraphQL Playground一款交互式 GraphQL IDE。在hello-world目录内运行prisma playground这会打开一个 Playground 窗口。补充Playground 也可作为独立桌面应用安装。如果本机没有安装桌面版该命令会自动在默认浏览器中打开 Web 版 Playground。从 playground/index.ts 的源码可以看到其完整逻辑命令会先检测 macOS 下的桌面应用路径是否存在不存在时启动一个本地 Express 服务器把/graphql代理到服务的真实端点默认端口为3000然后自动打开http://localhost:3000/playground。--web-w可强制使用 Web 版--port-p可指定端口--server-only-s则只启动服务器不打开浏览器。GraphQL API 有一个很酷的特性自文档化。GraphQL schema 定义了 API 的所有操作包括输入参数与返回类型这使得 GraphQL Playground 这类工具能自动生成 API 文档。点击 Playground 窗口右侧边缘的绿色SCHEMA按钮即可打开文档面板。最左侧一列是 API 支持的所有操作你可以逐层下钻查看每个操作的输入参数与返回类型细节。发送查询与变更现在可以真正向 API 发送查询和变更了。先从users查询开始取出数据库中当前存储的全部User节点。在 Playground 左侧编辑区输入以下查询然后点击Play按钮或使用快捷键CMDEnterquery { users { name } }此时服务只会返回空列表——这很正常因为我们还没有创建任何User节点。接下来用createUser变更在数据库中写入第一个User节点。在 Playground 中新建一个标签页输入以下变更并发送mutation { createUser(data: { name: Sarah }) { id } }这次服务器响应里终于有了数据注意id每次都会不同因为服务器在创建新节点时会生成全局唯一的 ID{ data: { createUser: { id: cjc69nckk31jx01505vgwmgch } } }回到之前包含users查询的标签页再次发送该查询。这次刚刚创建的User节点会出现在服务器响应中。过滤、排序与分页API 还提供了强大的过滤filtering、排序ordering与分页pagination能力。下面是给users查询传入相应输入参数的示例查询所有name包含字符串ra的User节点query { users(where: { name_contains: ra }) { id name } }按名字降序返回所有User节点query { users(orderBy: name_DESC) { id name } }分页取出列表中的第 20~29 个User节点query { users(skip: 20, first: 10) { id name } }下一步你已经走通了定义数据模型 → 部署 → 用 Playground 读写数据的完整闭环。在此基础上可以继续深入修改数据模型并重新部署体验改模型即改 API的联动效果见本系列下一篇 02-Changing-the-Data-Model.md深入了解prisma.yml的全部配置项与服务配置见 Service Configuration 参考学习 Prisma API 的完整操作、过滤与排序语法见 Prisma API 参考为生产环境启用认证在prisma.yml中设置secret、将disableAuth设为false并用prisma token生成 JWT 令牌。赞分享后端数据库GraphQL【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址https://gitcode.com/gh_mirrors/pr/prisma1点击查看免费下载相关推荐Prisma 快速入门用 Prisma 为数据库自动生成 GraphQL API 实战指南Prisma 快速入门用 Prisma 为数据库自动生成 GraphQL API 实战指南 本教程以 Prisma 1本仓库为 Prisma 1 的完整开源后端数据库GraphQLPrisma CLI 核心命令实战prisma-cli-core 如何把数据库变成 GraphQL APIPrisma CLI 核心命令实战prisma cli core 如何把数据库变成 GraphQL API 本文以 prisma cli core Pris后端数据库GraphQLSticky Parallax Header最佳实践从项目结构到部署上线的完整流程Sticky Parallax Header最佳实践从项目结构到部署上线的完整流程 Sticky Parallax Header是一个强大的React Nat后端数据库GraphQL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考