GraphQL 服务器的结构和实现(第三部分)

如果您之前编写过 GraphQL 服务器,您很可能已经遇到过传递到解析器中的 info 对象。幸运的是,在大多数情况下,您实际上不需要理解它实际做什么以及它在查询解析中的作用。
然而,在许多边缘情况下,info 对象是造成许多困惑和误解的原因。本文的目标是深入了解 info 对象,并阐明其在 GraphQL 执行 过程中的作用。
本文假设您已经熟悉 GraphQL 查询和 mutation 如何解析的基础知识。如果您在这方面感到有些不确定,您绝对应该查看本系列的前几篇文章:第一部分:GraphQL Schema(必需)第二部分:网络层(可选)
info
对象的结构
回顾:GraphQL 解析器的签名
快速回顾一下,当使用 GraphQL.js 构建 GraphQL 服务器时,您有两个主要任务
- 定义您的 GraphQL schema(以 SDL 或纯 JS 对象形式)
- 对于 schema 中的每个字段,实现一个解析器函数,该函数知道如何返回该字段的值
一个解析器函数接受四个参数(按该顺序)
parent
:先前解析器调用的结果(更多信息)。args
:解析器字段的参数。context
:每个解析器可以从中读取/写入的自定义对象。info
:这是我们将在本文中讨论的内容。
以下是简单 GraphQL 查询的执行过程以及所属解析器调用的概述。由于第二级解析器的解析是微不足道的,因此实际上不需要实现这些解析器——它们的返回值由 GraphQL.js 自动推断。

GraphQL 解析器链中 parent
和 args
参数的概述
info
包含查询 AST 和更多执行信息
那些对 info 对象的结构和作用感到好奇的人仍然茫然。官方 规范 和 文档 都没有提及它。曾经有一个 GitHub issue 请求更好地记录它,但该 issue 在没有明显行动的情况下关闭了。因此,除了深入研究代码之外,别无他法。
在非常高的层面上,可以说 info 对象包含传入 GraphQL 查询的 AST。因此,解析器知道它们需要返回哪些字段。
要了解有关查询 AST 外观的更多信息,请务必查看 Christian Joudrey 的精彩文章 GraphQL 查询的生命周期 — 词法分析/解析 以及 Eric Baer 的精彩演讲 GraphQL 底层原理。
要理解 info
的结构,让我们看一下 它的 Flow 类型定义
以下是每个键的概述和快速说明
fieldName
:如前所述,您的 GraphQL schema 中的每个字段都需要由解析器支持。fieldName
包含属于当前解析器的字段的名称。fieldNodes
:一个数组,其中每个对象代表剩余选择集中的一个字段。returnType
:对应字段的 GraphQL 类型。parentType
:此字段所属的 GraphQL 类型。path
:跟踪已遍历的字段,直到到达当前字段(即解析器)。schema
:代表您的可执行 schema 的GraphQLSchema
实例。fragments
:查询文档中 片段 的映射。rootValue
:传递给执行的rootValue
参数。operation
:整个查询的 AST。variableValues
:与查询一起提供的任何变量的映射对应于 variableValues 参数。
如果这仍然显得抽象,请不要担心,我们很快就会看到所有这些示例。
字段特定 vs 全局
关于上面的键,有一个有趣的观察。 info
对象上的键要么是字段特定的,要么是全局的。
字段特定的 简单地意味着该键的值取决于将 info
对象传递给的字段(及其支持的解析器)。明显的例子是 fieldName
、rootType
和 parentType
。考虑以下 GraphQL 类型的 author
字段
该字段的 fieldName
只是 author
,returnType
是 User!
,parentType
是 Query
。
现在,对于 feed
,这些值当然会有所不同:fieldName
是 feed
,returnType
是 [Post!]!
,parentType
也是 Query
。
因此,这三个键的值是字段特定的。进一步的字段特定键是:fieldNodes
和 path
。实际上,上面 Flow 定义的前五个键是字段特定的。
另一方面,全局的 意味着这些键的值不会改变——无论我们谈论的是哪个解析器。schema
、fragments
、rootValue
、operation
和 variableValues
将始终为所有解析器携带相同的值。
一个简单的例子
现在让我们继续看一个 info
对象内容的例子。为了设置阶段,这是我们将用于此示例的 schema 定义
假设该 schema 的解析器按如下方式实现
请注意,
Post.title
解析器实际上不是必需的,我们仍然在此处包含它以查看在调用解析器时info
对象的外观。
现在考虑以下查询
为了简洁起见,我们将只讨论 Query.author
字段的解析器,而不是 Post.title
的解析器(在执行上述查询时仍然会调用它)。
如果您想试用此示例,我们准备了一个 存储库,其中包含上述 schema 的运行版本,以便您可以进行实验!
接下来,让我们看一下 info
对象中的每个键,看看当调用 Query.author
解析器时它们的外观(您可以在 此处 找到 info
对象的完整日志输出)。
fieldName
fieldName
只是 author
。
fieldNodes
请记住,fieldNodes
是字段特定的。它有效地包含查询 AST 的摘录。此摘录从当前字段(即 author
)而不是查询的根开始。(从根开始的整个查询 AST 存储在 operation
中,请参阅下文)。
returnType
& parentType
如前所述,returnType
和 parentType
非常简单
path
path
跟踪已遍历到当前字段的字段。对于 Query.author
,它看起来很简单"path": { "key": "author" }
。
为了比较,在 Post.title
解析器中,path
如下所示
其余五个字段属于“全局”类别,因此对于
Post.title
解析器将是相同的。
schema
schema
是对可执行 schema 的引用。
fragments
fragments
包含片段定义,由于查询文档没有任何片段定义,因此它只是一个空映射:{}
。
rootValue
如前所述,rootValue
键的值对应于最初传递给 graphql 执行函数的 rootValue
参数。在示例中,它只是 null
。
operation
operation
包含传入查询的完整 查询 AST。回想一下,除其他信息外,这还包含我们上面看到的 fieldNodes
的相同值
variableValues
此键表示为查询传递的任何变量。由于我们的示例中没有变量,因此此键的值再次只是一个空映射:{}
。
如果查询是用变量编写的
variableValues
键将只具有以下值
使用 GraphQL bindings 时 info
的作用
正如本文开头提到的,在大多数情况下,您根本不需要担心 info
对象。它只是恰好是您的解析器签名的一部分,但您实际上并没有将其用于任何目的。那么,它什么时候变得相关呢?
将 info
传递给 binding 函数
如果您之前使用过 GraphQL bindings,您已经看到 info
对象是生成的 binding 函数的一部分。考虑以下 schema
使用 graphql-binding
,您现在可以通过调用专用的binding 函数而不是发送原始查询和 mutation 来发送可用的查询和 mutation。
例如,考虑以下原始查询,检索特定的 User
使用 binding 函数实现相同目的的外观如下
通过调用 binding 实例上的 user
函数并传递相应的参数,我们传达的信息与上面的原始 GraphQL 查询完全相同。
graphql-binding
中的 binding 函数接受三个参数
args
:包含字段的参数(例如,上面createUser
mutation 的username
)。context
:向下传递解析器链的context
对象。info
:info
对象。请注意,除了GraphQLResolveInfo
的实例(它是 info 的类型)之外,您还可以传递一个字符串,该字符串仅定义选择集。
使用 Prisma 将应用程序 schema 映射到数据库 schema
info 对象可能引起混淆的另一个常见用例是基于 Prisma 和 prisma-binding 实现 GraphQL 服务器。
在这种情况下,想法是有两个 GraphQL 层
- 数据库层 由 Prisma 自动生成,并提供通用且强大的 CRUD API
- 应用程序层 定义暴露给客户端应用程序并根据您的应用程序需求定制的 GraphQL API
作为后端开发人员,您负责为应用程序层定义应用程序 schema 并实现其解析器。感谢 prisma-binding
,解析器的实现仅仅是将传入查询委托到基础数据库 API 的过程,而没有主要开销。
让我们考虑一个简单的例子——假设您从以下数据模型开始构建您的 Prisma 数据库服务
Prisma 基于此数据模型生成的数据库 schema 看起来类似于这样
现在,假设您想要构建一个应用程序 schema,使其看起来类似于这样
feed
查询不仅返回 Post
元素的列表,而且还能够返回列表的 count
。请注意,它可选地接受一个 authorId
,该 authorId
过滤 feed 以仅返回由特定 User
编写的 Post
元素。
实现此应用程序 schema 的第一个直觉可能如下所示。
实现 1:此实现看起来正确,但有一个细微的缺陷
此实现看起来足够合理。在 feed
解析器内部,我们正在基于可能传入的 authorId
构建 authorFilter
。authorFilter
然后用于执行 posts
查询并检索 Post
元素,以及 postsConnection
查询,该查询允许访问列表的 count
。
也可以仅使用 postsConnection 查询来检索实际的 Post 元素。为了简单起见,我们仍然使用 posts 查询来实现该目的,并将另一种方法留给细心的读者作为练习。
实际上,当使用此实现启动 GraphQL 服务器时,最初看起来一切都很好。您会注意到简单的查询得到了正确处理,例如,以下查询将成功
只有当您尝试检索 Post
元素的 author
时,您才会遇到问题
好的!因此,由于某种原因,该实现没有返回 author
,这会触发错误 “Cannot return null for non-nullable Post.author.”,因为 Post.author
字段在应用程序 schema 中标记为必需。
让我们再次看一下实现的相关部分
这是我们检索 Post 元素的地方。但是,我们没有将选择集 传递给 posts binding 函数。如果未将第二个参数传递给 Prisma binding 函数,则默认行为是查询该类型的所有标量字段。
这确实解释了这种行为。对 ctx.db.query.posts
的调用返回正确的 Post
元素集,但仅返回它们的 id
和 title
值——没有关于 author
的关系数据。
那么,我们如何解决这个问题呢?显然需要一种方法来告诉 posts
binding 函数它需要返回哪些字段。但是,该信息驻留在 feed
解析器的上下文中什么位置?你能猜到吗?
正确: 在 info
对象内部!因为 Prisma binding 函数的第二个参数可以是字符串或 info
对象,所以让我们只将传递到 feed
解析器中的 info
对象传递给 posts
binding 函数。
此查询在实现 2 中失败:“类型为 ‘Post’ 的字段 ‘posts’ 必须有一个子选择。”
但是,使用此实现,所有请求都将无法正确处理。例如,考虑以下查询
错误消息 “类型为 ‘Post’ 的字段 ‘posts’ 必须有一个子选择。” 由上述实现的第 8 行 生成。
那么,这里发生了什么?失败的原因是 info
对象中字段特定的 键与 posts
查询不匹配。
打印 feed
解析器内部的 info
对象可以更清楚地了解情况。让我们仅考虑 fieldNodes
中字段特定的信息
此 JSON 对象也可以表示为字符串选择集
现在一切都说得通了!我们正在将上述选择集发送到 posts
Prisma 数据库 schema 的查询,当然,该 schema 不知道 feed
和 count
字段。诚然,生成的错误消息不是很有帮助,但至少我们现在明白了发生了什么。
那么,解决此问题的方案是什么?解决此问题的一种方法是手动解析出 fieldNodes
选择集的正确部分,并将其传递给 posts
binding 函数(例如,作为字符串)。
但是,有一个更优雅的解决方案可以解决该问题,那就是为应用程序 schema 中的 Feed
类型实现专用解析器。以下是正确实现的外观。
实现 3:此实现修复了上述问题
此实现修复了上面讨论的所有问题。有几件事需要注意
- 在第 8 行中,我们现在传递一个字符串选择集(
{ id }
)作为第二个参数。这只是为了提高效率,因为否则将获取所有标量值(这在我们的示例中不会产生巨大差异),而我们只需要 ID。 - 我们没有从
Query.feed
解析器返回posts
,而是返回postIds
,它只是一个 ID 数组(表示为字符串)。 - 在
Feed.posts
解析器中,我们现在可以访问由 parent 解析器返回的postIds
。这次,我们可以利用传入的info
对象,并简单地将其传递给posts
binding 函数。
如果您想试用此示例,可以查看 这个 存储库,其中包含上述示例的运行版本。随意尝试本文中提到的不同实现,并自行观察行为!
总结
在本文中,您深入了解了在基于 GraphQL.js 实现 GraphQL API 时使用的 info
对象。
info
对象没有正式文档——要了解更多信息,您需要深入研究代码。在本教程中,我们首先概述了其内部结构,并了解了其在 GraphQL 解析器函数中的作用。然后,我们介绍了一些边缘情况和潜在陷阱,在这些情况下,需要更深入地了解 info
。
本文中显示的所有代码都可以在相应的 GitHub 存储库中找到,因此您可以自己进行实验并观察 info 对象的行为。
不要错过下一篇文章!
注册 Prisma 新闻通讯