Go 使用 GraphQL - 基础教程

欢迎golang同胞！在本教程中，我们将研究如何在基于 Go 的程序中与 GraphQL 服务器进行交互。在本教程结束时，我们应该知道如何执行以下 *** 作：

在本教程中，我们将专注于学习 GraphQL 的数据检索方面，并且我们将使用内存中的数据源来支持它。这应该为我们在后续教程的基础上建立一个良好的基础。

好的，所以在我们深入研究之前，我们应该真正了解 GraphQL 的基础知识。作为开发人员，使用它对我们有什么好处？

好吧，考虑使用每天处理数十万甚至数百万请求的系统。传统上，我们会使用位于数据库前面的系统 API，它会返回大量 JSON 响应，其中包含许多我们可能不一定需要的冗余信息。

如果我们正在处理大规模的应用程序，发送冗余数据的成本可能会很高，并且由于有效负载大小会阻塞我们的网络带宽。

GraphQL基本上可以让我们以减少噪音和描述数据，我们希望让我们的检索，从我们的API中检索 只有 我们需要为我们当前的任务/视图/不管。

这只是该技术为我们提供的众多好处的一个例子。希望在接下来的教程系列中，我们会提前看到更多这些好处。

需要注意的重要一点是，GraphQL 不像我们传统的 SQL 那样是一种查询语言。它是位于我们 API 前面的抽象， 不 依赖于任何特定的数据库或存储引擎。

这真的很酷。我们可以建立一个与现有服务商交互的 GraphQL 服务器，然后围绕着这个新的 GraphQL 服务器构建，而不必担心修改现有的 REST API。

让我们看看 RESTful 方法与 GraphQL 方法有何不同。现在，假设我们正在构建一个返回该站点上所有教程的服务，如果我们想要特定教程的信息，我们通常会创建一个 API 端点，允许我们根据 ID 检索特定教程：

如果给定一个 valid ID，这将返回一个响应，看起来像这样：

现在，假设我们想创建一个小部件，列出该作者撰写的书籍 5 个帖子。我们可以点击/author/:id端点以检索该作者撰写的所有帖子，然后进行后续调用以检索前 5 个帖子中的每一个。或者，我们可以制作一个全新的端点来为我们返回这些数据。

这两种解决方案听起来都不是特别吸引人，因为它们会创建不需要的请求量或返回过多的数据，这突出了 RESTful 方法开始出现一些裂缝的地方。

这就是 GraphQL 发挥作用的地方。使用 GraphQL，我们可以定义我们希望在查询中返回的数据的确切结构。所以如果我们想要上面的信息，我们可以创建一个看起来像这样的查询：

这将随后返回我们的教程、该教程的作者和一组表示该作者编写的教程的教程 ID，而无需发送额外的 x 多个 REST 请求来获取信息！那有多好？

好的，现在我们对 GraphQL 以及对它的用途有了更多的了解，让我们在实践中看看它。

我们将使用graphql-go/graphql实现在 Go 中创建一个简单的 GraphQL 服务器 。

让我们首先使用go mod init以下方法初始化我们的项目：

接下来，让我们创建一个名为main.go. 我们将从简单开始创建一个非常简单的 GraphQL 服务器，它具有一个非常简单的解析器：

现在，如果我们尝试运行它，让我们看看会发生什么：

所以，如果一切正常，那么我们就可以设置一个非常简单的 GraphQL 服务器并对这个服务器进行非常简单的查询。

让我们分解上面代码中发生的事情，以便我们可以进一步扩展它。在lines 14-21我们定义我们的Schema. 当我们对我们的 GraphQL API 进行查询时，我们基本上定义了我们想要返回给我们的对象上的哪些字段，因此我们必须在我们的 Schema 重新定义这些字段。

在 上line 17，我们定义了一个解析器函数，每当field请求此特定内容时就会触发该解析器函数。现在，我们只是返回字符串 "world"，但我们将实现从这里查询数据库的能力。

让我们看一下main.go文件的第二部分。在line 30我们开始定义query请求领域hello。

然后我们创建一个params结构，其中包含对我们定义的Schema以及我们的RequestString请求的引用 。

最后，在line 36我们执行请求并将请求的结果填充到r. 然后我们进行一些错误处理，然后将响应编组为 JSON 并将其打印到我们的控制台上。

现在我们已经启动并运行了一个非常简单的 GraphQL 服务器，并且我们能够对其进行查询，让我们更进一步，构建一个更复杂的示例。

我们将创建一个 GraphQL 服务器，它返回一系列内存中的教程及其作者，以及对这些特定教程的任何评论。

让我们定义一些struct代表 a Tutorial、 anAuthor和 a 的's Comment：

然后我们可以创建一个非常简单的populate()函数，它将返回一个类型数组Tutorial：

这将为我们提供一个简单的教程列表，然后我们可以稍后解决。

我们将从使用 GraphQL 创建一个新对象开始graphql.NewObject()。我们将使用 GraphQL 的严格类型定义 3 种不同的类型，它们将与structs我们已经定义的 3 种相匹配。

我们的Commentstruct 可以说是最简单的，它只包含一个 string Body，所以我们可以commentType很容易地将其表示为：

接下来，我们将处理该Author结构并将其定义为一个新的 graphql.NewObject(). 这会稍微复杂一些，因为它既有一个 String字段，也有一个Int值列表，这些值代表他们编写的教程的 ID。

最后，让我们定义我们的tutorialTypewhich 将封装 an author和comment's的数组以及 anID和 a title：

现在我们已经定义了我们的Type系统，让我们着手更新我们的 Schema 以反映这些新类型。我们将定义 2 个 distinct Field，第一个将是我们的tutorial字段，它允许我们Tutorials 根据传入查询的 ID检索个人。第二个将是一个list字段，它将允许我们检索Tutorials我们在内存中定义的完整数组。

所以我们已经创建了我们的类型并更新了我们的 GraphQL 模式，我们做得还不错！

让我们尝试使用我们的新 GraphQL 服务器并处理我们提交的查询。让我们来尝试我们的list架构改变query ，我们已经在我们得到main()的功能：

让我们分解一下。所以在我们的查询中，我们有一个特殊的root对象。然后我们在其中说我们想要该list对象上的字段。在返回的名单list，我们希望看到的id，title，comments和 author。

当我们运行它时，我们应该会看到以下输出：

正如我们所见，我们的查询以 JSON 格式返回了我们所有的教程，看起来非常像我们初始查询的结构。

现在让我们尝试对我们的tutorial模式进行查询：

再一次，当我们运行它时，我们应该看到它已经成功地检索了内存中的单独教程ID=1：

完美，看起来我们已经让list我们的tutorial模式和我们的模式都按预期工作了。

这就是我们将在这个初始教程中介绍的全部内容。我们已经成功地设置了一个简单的 GraphQL 服务器，该服务器由内存数据存储支持。

在下一个教程中，我们将研究 GraphQL 突变并更改我们的数据源以使用 SQL 数据库

在 GraphQL（一）：GraphQL介绍 中讲到目前已经有很多平台完成了GraphQL实现，这里以Java平台为例，介绍GraphQL服务的搭建。

graphql-java 是GraphQL的Java实现，它实现了GraphQL的执行，但是没有任何关于HTTP或者JSON的处理，因此在接入SpringBoot时还需要 graphql-java-spring 的支持。官方的 案例 就是使用这两个jar包完成的。

在官方的 案例 中，我们需要实例化一个GraphQL实例：

这样的实现需要我们了解较多graphql-java的底层细节，比如：TypeDefinitionRegistry、RuntimeWiring、SchemaGenerator等，同时还需要硬编码字符串。

同样，在实现数据注入时，也需要硬编码：

于是就有了 graphql-spring-boot-starter + graphql-java-tools 搭建GraphQL的方案。

graphql-java-tools 能够从GraphQL的模式定义 .graphqls 文件构建出对应的Java的POJO类型对象（graphql-java-tools将读取classpath下所有以 .graphqls为后缀名的文件，创建GraphQLSchema对象），同时为我们屏蔽了graphql-java的底层细节，它本身依赖graphql-java。

graphql-spring-boot-starter 是辅助SpringBoot接入GraphQL的库，它本身依赖graphql-java和 graphql-java-servlet （将GraphQL服务发布为通过HTTP可访问的Web服务，封装了一个GraphQLServlet接收GraphQL请求，并提供 Servlet Listeners 功能）。

接下来我们将实现一个基于 graphql-spring-boot-starter + graphql-java-tools 搭建GraphQL服务的Demo。

对应的SpringBoot版本是1.5.6

以及对应的Dao、Service、teacher.xml等

这里的模型最好和Java Bean一致，如果Java bean中有多余的字段，将被忽略，不会抛出异常。

这是公开API的地方，按照GraphQL的规范，Query、Mutation、Subscription三种查询类型需要放在各自的节点下（这里暂时不考虑订阅）：

graphql-java-tools为我们屏蔽了底层细节，我们只需要继承以下几个类完成数据注入即可：

Resolver完成的是数据的注入，也就是对*.graphqls文件中的type的字段的数据进行注入，注入需要满足以下规则：

比如我们我们根据学校Id查询学校的API：

我们在schema.graphqls中定义的类型有与之对应的Java Bean，这些Java Bean都提供了getField方法，因此不需要额外实现Resolver，有时候，在type中定义的类型的某个字段数据的获取比较麻烦，不是简单的getField可以解决的，此时可以为此类型实现专门的字段值获取的Resolver，假设School中的master字段逻辑获取逻辑很复杂：

泛型中需要指定类型，字段数据获取的方法名称规则和常规接口的规则一致，只是需要把该类型作为参数传递到方法内，值得注意的是，如果客户端没有请求Master字段，那么getMaster方法将不会被执行。

实际上针对type中的每个Field都需要有getField，使得Graphql能够获取到数据注入到返回的结果中，如果针对此Field已经实现了Resolver，那么会优先使用Resolver来注入数据，此时可以省略掉getField（直接去掉School Bean中的master字段）不过还是建议将Java Bean和type中的Field一一对应，便于维护。

以上是针对Query的Demo，关于Mutation请查看文本的源码，这里需要说明的是我们的insertSchool和insertTeacher有些不同：

insertTeacher引入了一个新类型TeacherInput，将需要传递到服务端的数据封装起来，GraphQL的返回类型（Teacher）和输入类型（TeacherInput）是不能共用的，所以加上Input后缀加以区分，同样的，针对TeacherInput也需要有对应的Java Bean。

graphql 新API 开发方式

我们知道 GraphQL 使用 Schema 来描述数据，并通过制定和实现 GraphQL 规范 定义了支持 Schema 查询的 DSQL （Domain Specific Query Language，领域特定查询语言）。Schema 帮助将复杂的业务模型数据抽象拆分成细粒度的基础数据结构，而 DSQL 的实现则赋予了前端开发者自由组织和定制请求数据的能力。如果以一张图来表示的话，可以将 GraphQL 看做一条以 通用基础业务数据模型 为基础、将传统后端服务和前端页面紧密且自由地联系在一起的纽带。

为什么 GraphQL 的 Schema 能够表示出服务器所支持的复杂业务模型数据，GraphQL 的 Query 又是怎样赋予前端开发者对数据的定制能力，本文将通过分析和理解 GraphQL 的设计来和大家一起探讨解答这些问题。

1.GraphQL 的设计

GraphQL 由以下组件构成：

作为将数据模型和具体接口实现解耦的 DSL，GraphQL 的基础组件，也是它最重要的组件之一就是类型系统。

1.1 类型系统

可以将 GraphQL 的类型系统分为标量类型（Scalar Types，标量类型）和其他高级数据类型，标量类型即可以表示最细粒度数据结构的数据类型，可以和 JavaScript 的原始类型对应。GraphQL 规范目前规定支持的标量类型有：

Scalar Types 的 JavaScript 参考实现代码可以查看 这里 。

其他高级数据类型包括：

还有一种重要的数据类型，即 schema 类型，它描述了后端服务器能够提供的数据支持。这里先暂时不介绍，因为它涉及 GraphQL 的其他组件，等全部介绍完我们再来看 GraphQL 中 schema 的 具体实现 。

1.2 查询语言

类型系统对应我们开头提到的 Schema，是对服务器端数据的描述，而查询语言则解耦了前端开发者与后端接口的依赖。前端开发者利用查询语言可以自由地组织和定制系统能够提供的业务数据。

GraphQL 的一个查询请求被称为一份 query 文档（query document），即 GraphQL 服务能够解析验证并执行的一串请求字符串。query 由 *** 作（Operation）和片段（Fragments）组成。一个 query 可以包含多个 *** 作和片段。只有包含 *** 作的 query 才会被 GraphQL 服务执行。但是不包含 *** 作，只有片段的 query 也会被 GraphQL 服务解析验证，这样一份片段就可以在多个 query 文档内使用。

只包含一个 *** 作的 query 可以不带 *** 作名称或者使用简写形式（即 query 关键字加 *** 作名）。query 包含多个 *** 作时，所有 *** 作都必须带上名称。

*** 作（Operations）

GraphQL 规范支持两种 *** 作：

查询请求的模型可以用下面的图来表示：

选择集合（Selection Sets）

选择集合表示当前选中的数据内容，格式为：

关于选择集合的使用，可以参考 graphql-js 的代码 。参考实现代码在 这里 。

字段（Field）

字段格式为：

alias:name(argument:value)

其中 alias 是字段的别名，即结果中显示的字段名称。

name 为字段名称，对应 schema 中定义的 fields 字段名。

argument 为参数名称，对应 schema 中定义的 fields 字段的参数名称。

value 为参数值，值的类型对应标量类型的值。

例如这样的请求： http://yunhe.taobao.com/?query={banner{backgroundURL:bg,biaoti:slogan}}

backgroundURL 就是 bg 字段的别名。

片段（Fragment）

片段是 GraphQL 的主要组合数据结构，通过片段可以重用重复的字段选择，减少 query 中的重复内容。片段又分为 FragmentSpread 和 InlineFragment。例如没有片段时需要这样编写 query：

query 中存在下列重复的选择集合：

可以用片段简化为：

使用片段时需要加上 ... *** 作符表示展开片段内容。

内联片段示例如下：

指令（Directives）

指令要解决的是 query 执行时字段参数无法覆盖的情况，例如引入或者忽略某个字段。指令为 GraphQL 执行添加了更多的信息。

指令实例如下：

include 指令表示只有在 if 参数为 true 时才引入片段表示的字段。

skip 指令表示在 if 参数为 true 时忽略片段中的字段。

熟悉了 类型系统 和 查询语言 我们就可以用 GraphQL 来实现应用层的数据请求了。其他三个 GraphQL 组件更偏向于 DSL 的实现和原理，因此本文不再做详细介绍，感兴趣的同学可以对照 规范 和 参考实现 自己研究。

2.总结

GraphQL 是在应用层对业务数据模型的抽象，是对数据请求定制的 DSQL，它解除了接口和数据之间的绑定，对业务数据结构做了抽象和整理，业务逻辑中的数据依赖于底层数据库结构，并且可以由具体业务场景来定制，不同的业务场景只要基于同样一套基础业务数据模型就可以得到复用，在我看来，这才是 GraphQL 带来的最大改变和收益。

---