PRISMA基础:入门一

本文属使用Prisma构建GraphQL服务系列。

本教程学习如何使用Prisma对数据库生成GraphQL API。

主要步骤如下：

• 安装Prisma CLI
• 使用prisma init构建Prisma服务
• 使用GraphQL Playground查看API，发送查询(queries)和突变(mutations)

安装Prisma CLI

使用Prisma CLI管理Prisma服务。
可使用npm(或yarn)安装。

打开终端工具，运行如下命令安装Prisma CLI:

npm install -g prisma
# or
# yarn global add prisma

构建Prisma服务

打开终端，跳转到任意目录。然后用如下命令构建Prisma 服务:

prisma init hello-world

此命令创建一个hello-world新目录，包括2个必须的文件:

• prisma.yml:服务的根配置文件，包含有关服务的信息，例如名称（用于生成服务的HTTP端点），用于保护对端点访问的及应该在何处部署的secret。
• datamodel.graphql(也可能为不同名称，如types.graphql):此文件使用GraphQL SDL定义数据模型(data model)。

来看看生成的文件：

prisma.yml

endpoint: https://eu1.prisma.sh/public-mountainninja-311/hello-world/dev
datamodel: datamodel.graphql

注意，endpoint对于会略有不同，因为public-mountainninja-311是随机生成的ID，对于部署到Sandbox的每个Prisma API都会有所不同。

以下是生成的prisma.yml中的属性说明：

• endpoint:定义Prisma API的HTTP端点;
• datamodel:所包含数据模型的文件的路径。

datamodel.graphql

type User {
  id: ID! @unique
  name: String!
}

数据模型包含应用程序域中实体的类型定义。此刻，您将开始使用带有id和name的非常​​简单的User类型。

@unique指令(directive)表示数据库中每个User的id唯一，Prisma会始终确保其唯一。

Prisma API现已部署并准备好接收查询(queries)，突变(mutations)和订阅(subscriptions)。

使用GraphQL Playground查看API

你的API已被部署 - 但你怎么知道如何与它交互？它的API实际上是什么样的？

通常，生成的API允许对数据模型中的类型执行CRUD操作。它还公开了GraphQL订阅，允许客户订阅特定事件并实时接收更新。

了解数据模型是API的基础很重要。每次对数据模型进行更改（并运行prisma deploy之后）时，GraphQL API都会相应更新。

由于您的数据模型包含User类型，因此Prisma API现在允许其客户端创建，读取，更新和删除该类型的实例（也称为节点nodes）。尤其是，现在基于User类型生成以下GraphQL操作：

• user:通过其id查询（或另一个@unique字段）检索单个User节点
• users:查询以检索User节点列表。
• createUser: 突变(Mutation)创建一个新的User节点。
• updateUser: 突变(Mutation)更新现存User节点。
• deleteUser: 突变(Mutation) 删除现存User节点。

注意：以上操作列表不完整。 Prisma API公开了多个操作，例如，允许批量更新/删除许多节点。但是，所有操作都可以创建，读取，更新或删除数据模型中定义的类型的节点。

要实际使用这些操作，您需要一种将请求发送到服务API的方法。由于该API通过HTTP公开，因此您可以使用curl或Postman等工具与之交互。但是，GraphQL实际上具有更好的工具：GraphQL Playground，一种交互式GraphQL IDE。

要打开GraphQL Playground，可以再次使用Prisma CLI。只需在hello-world目录中运行以下命令：

prisma playground

这将打开一个GraphQL Playground，如下图：

GraphQL Playground

注意：Playground可以作为独立的桌面应用程序安装在您的机器上。如果您没有安装Playground，该命令会自动在您的默认浏览器中打开一个Playground。

GraphQL API的一个非常酷的特性是它们有效地自我说明。 GraphQL Scheme定义了API的所有操作，包括输入参数和返回类型。这允许像GraphQL Playground这样的工具自动生成API文档。

要查看Prisma API的文档，请单击Playground窗口右边缘上的绿色SCHEMA按钮。

这带来了Playground的文档窗格。最左边的列是API接受的所有操作的列表。然后，您可以深入了解每个操作涉及的输入参数或返回类型的详细信息。

GraphQL API Documents

发送查询和突变(queries and mutations)

好吧！借助迄今为止学到的一切，您已准备好针对您的API发布一些查询和突变(queries and mutations)。让我们从users查询开始，检索当前存储在数据库中的所有User节点。 在左边的Playground窗格中输入以下查询，然后单击Play按钮（或使用快捷键CMD + Enter）：

query {
  users {
    name
  }
}

此时，服务器只返回一个空列表。这并不奇怪，因为我们到目前为止还没有实际创建任何User节点。因此，让我们改变它，并使用createUser突变将第一个User节点存储在数据库中。

在Playground中打开一个新选项卡，在左边的Play中输入以下突变:

mutation {
  createUser(data: {
    name: "Sarah"
  }) {
    id
  }
}

这一次，服务器的响应实际上包含了一些数据（请注意，当服务器在创建时为每个新节点生成一个全局唯一的ID时，该ID当然会有所不同）

{
  "data": {
    "createUser": {
      "id": "cjc69nckk31jx01505vgwmgch"
    }
  }
}

您现在可以返回到users查询的前一个选项卡，并再次发送查询。
这次，刚刚创建的User节点在服务器响应中返回：

users

请注意，API还提供强大的过滤，排序和分页功能。以下是为user查询提供相应输入参数的查询示例。

检索name包含字符串“ra”的所有User节点

query {
  users(where: {
    name_contains: "ra"
  }) {
    id
    name
  }
}

检索按name降序排列的所有User节点

query {
  users(orderBy: name_DESC) {
    id
    name
  }
}

检索一部分User节点（列表中的位置20-29）

query {
  users(skip: 20, first: 10) {
    id
    name
  }
}