2. GraphQL 基础
1m

概述

在本课中,我们将

  • 探讨“Schema 优先”设计
  • 了解以下内容的基础知识 ()

定义数据

在动手之前,我们需要回答一个重要问题:我们需要哪些数据来构建此功能?

让我们看看设计团队为我们绘制的模型。以下是主页应具有的样子:一个整洁的卡片网格。

A mockup of the app, showing a grid of learning track cards

在继续之前,请花点时间查看模型并确定哪些信息可能需要来填充单个卡片。

任务!

基于模型,似乎我们需要为每个学习路径提供以下信息

  • 标题
  • 缩略图
  • 时间长度(估计持续时间)
  • 模块数量
  • 作者姓名
  • 作者图片
A doodle identifying the pieces of data for each track card

图表

查看以上列表,我们可以开始将我们应用程序的数据视为 对象集合(例如学习路径和作者)以及对象之间的 关系(例如每个学习路径都有一位作者)。

现在,如果我们将每个对象看做一个 节点,将每段关系视为两个节点之间的 ,那么我们可以将整个数据模型看做一个 ,其中包括节点和边。这就是我们应用程序的

以下是我们应用程序的 的不完整表示,它完全基于我们模型的数据需求:

A doodle of a graph, consisting of nodes with relationships to other nodes

结构反映了我们期望在 )中发现的关系类型,该 详细说明了我们应用程序数据能力的类型、 和关系!

通过在开始时定义我们前端所需的数据类型,我们采用了一种策略,称为 模式优先设计

模式优先设计

还记得我们在上一课中提到的模式吗?(提示:它是 ,它定义了我们所处理的数据类型,以及它们之间的关系!)

那么,“模式优先”设计是一种通用约定,后端和前端团队在使用 时使用它。它使我们能够根据我们的客户端应用程序所需的数据类型,精确地实现我们的

模式优先设计通常涉及三个主要步骤

  1. 定义模式:我们确定我们的功能需要哪些数据,然后我们构建我们的模式,以尽可能直观地提供该数据。前端和后端之间的协作在这里至关重要!
  2. 后端实施:我们在服务器端构建我们的 API,从包含所需数据的任何 中获取并准备这些数据。
  3. 前端实施:我们的客户端从我们的 API 消耗数据,以呈现其视图。

为了完成本课程,我们将标记第 1 步和第 2 步已完成——我们刚刚浏览了所需数据,并且我们可以想象我们的后端团队已经定义了模式并实现了服务器逻辑。现在,我们的工作重点是第三步:使用 API 提取数据并呈现视图!

为此,我们需要熟悉 模式定义语言(或 )。

如果您已熟悉 ,请随时进入下一课。

模式定义语言 (SDL)

我们的模式充当服务器和客户端之间的 ,定义 API 可以或不可以执行哪些操作,以及客户端如何请求或更改数据。这是一个抽象层,为使用者提供灵活性,同时隐藏后端实现细节。

我们使用 )来定义构成模式的 对象类型字段

类型和字段

类型以 type关键字开头,后接类型名称(帕斯卡命名法是一种最佳实践),然后用花括号括起包含的

type Track {
# Fields go here
}

通过字段名称(驼峰式)、冒号和字段的类型(或对象)进行声明。

type Track {
title: String
}

架构中的每个 都有自己的一个类型。字段的类型可以是 标量(例如上面所示的 IntString),也可以是 另一个对象类型

type Track {
title: String
author: Author
}

一个 还可以包含一个列表,列表用方括号表示:

type Track {
title: String!
author: Author!
modules: [Module]
}

与 Javascript 对象(非常相似)不同的是, 之间不会用逗号分隔。

此外,我们可以指示每个 的值是否可空或者不可空。如果一个字段永远不可为空,那么我们可以在其类型后添加一个感叹号:

type Track {
title: String!
author: Author!
modules: [Module!]!
}

描述

最好做法是架构,就像对代码进行注释一样。描述让使用者更容易理解 API 中发生了什么。它们还可以允许诸如之类的工具(下一课将详细介绍!)指导 API 使用者在需要时和需要的位置使用 API 完成哪些任务。

中描述可通过直接在它们上面写字符串(使用引号)应用于

"I'm a regular description"

三重“双引号”允许您添加换行符以更清晰地格式化较长的注释。

"""
I'm a block description
with a line break
"""

下面是Track类型,已使用一些有用的描述更新!

"A track is a group of Modules that teaches about a specific topic"
type Track {
"The track's title"
title: String!
"The track's main Author"
author: Author!
"The track's complete array of Modules"
modules: [Module!]!
}

GraphQL API

我们将使用预先构建的API 使我们的前端焕然一新。让我们使用Apollo Sandbox来了解此 API。Sandbox 是的一种特殊模式,允许您在整个课程中将探索的大量功能中,测试API。

让我们打开浏览器到Sandbox Schema Reference 页面。在这里,我们将看到Schema概览页面,但是现在还没有太多内容可以看。看到屏幕顶部的红点了吗?这表示 Sandbox 尚未连接到任何内容。

http://studio.apollographql.com/sandbox/schema/reference

A screenshot of the Schema page in Sandbox

我们先将其连接到整个课程中都将使用的API。复制以下 URL,然后将其粘贴到页面顶部端点输入中。

到我们 GraphQL API 的端点
https://odyssey-lift-off-server.herokuapp.com/

几分钟后,我们将会看到点变成绿色,即 Sandbox 已成功连接到我们的 API!我们还将注意到界面更新了一些新数据。

http://studio.apollographql.com/sandbox/schema/reference

The Schema Reference page in Sandbox, now connected to a GraphQL API

让我们点击 对象左菜单中的选项。这将我们带到 API 的 对象类型;它们描述此 API 架构处理的不同对象。

http://studio.apollographql.com/sandbox/schema/reference

The Schema Reference page in Sandbox, highlighting the Objects option in the left-hand menu

为我们提供有关音轨、模块及其作者的数据,此 API 架构包含一些 我们可能预期: TrackModuleAuthor。(稍后我们会了解到那个 IncrementTrackViewsResponse类型!)

http://studio.apollographql.com/sandbox/schema/reference/objects

The Schema Reference page in Sandbox, opened to the Objects page

我们可以点击 Track类型来仔细查看它包含的数据类型。

http://studio.apollographql.com/sandbox/schema/reference

The Schema Reference page in Sandbox, opened to the Track page

此类型让我们清晰了解了音轨对象中包含的所有内容: 我们可以在此类型中访问,以及它们的描述和它们返回的数据类型。

我们还可以开始设想一个 如何与另一个相关联。例如,每个 Track实例都有一个 author ,它返回一个新的 Author!此外,我们预期每个 Track都包含 Module类型的列表。

http://studio.apollographql.com/sandbox/schema/reference

The fields on the Track type, highlighting the author and modules fields which each return an object type

但架构仅有这三个 是不够的;我们还需要一种实际上 向我们的 API 请求数据的方式。

Query类型

为我们可采用以访问我们数据的方式提供定义,我们的架构提供 查询 类型。例如,我们希望 歌曲的列表,而查询 类型为我们提供了一种方式来实现这一点!

让我们回到 查询 页面,通过退出沙盒视图中的 对象类型 并返回到 查询 页面。

http://studio.apollographql.com/sandbox/schema/reference

The Query page highlighted in the Schema Reference page

存在于 查询 类型中的每个 都可以被认为是我们数据的一个“入口点”。它定义了我们可要求的某个非常具体的事项(例如 tracksForHome)以及我们可预期从运行此 接收的数据类型(一个由非空 Track 类型组成的非空列表)。

http://studio.apollographql.com/sandbox/schema/reference

The Query page scrolled down to show the different fields on the type

尽管我们一直保持对架构的观察基本上属于宏观层面,但你可以深入研究将此架构结合在一起的实际语法。

架构 页面选择顶部处的 SDL 选项。这将打开整个 API(以其原始 存在),供你浏览!

http://studio.apollographql.com/sandbox/schema/reference

The Schema page opened to the SDL tab, showing the SDL for the GraphQL API

让我们对我们了解到的有关我们的架构及其类型的知识,然后看看我们如何实际应用它们来使用一些数据!

练习

下列哪项准确地描述了 GraphQL 中的图表?

> 主要要点

  • 模式,以定义语言) 编写。
  • 通过添加感叹号 (!),可以将标记为非空。
  • 中,描述包含在一对双引号 ("单行描述"),或包含在三对双引号 ("""多行描述""") 中。
  • 模式的Query类型定义 API 的入口点,并限制可以查询的数据类型。
  • 沙盒是的一种特殊模式,让你可以浏览和测试API。

后续

我们已经从模式的角度探索了 API 的类型和;现在是时候了解如何使用这些定义构建查询,并获取一些数据了!在下一节中,我们将开动 API 试用一下。

上一步

分享你对本课程的问题和评论

此课程目前处于

测试版
.你的反馈有助于我们改进!如果你遇到困难或感到困惑,请告诉我们,我们会帮助你。所有的评论都是公开的,必须遵循 Apollo 行为准则。请注意,已经解决或回复的评论可能会被删除。

你需要一个 GitHub 帐户才能在下方发帖。还没有一个? 相反,请在我们的 Odyssey 论坛中发布。