使用ASP.NET Core开发GraphQL服务器 -- 预备知识(上)

为了介绍使用ASP.NET Core构建GraphQL服务器，本文需要介绍一下GraphQL，其实看官网的文档就行。

什么是GraphQL？

GraphQL 既是一种用于 API 的查询语言也是一个满足你数据查询的运行时。 GraphQL 对你的 API 中的数据提供了一套易于理解的完整描述，使得客户端能够准确地获得它需要的数据，而且没有任何冗余，也让 API 更容易地随着时间推移而演进，还能用于构建强大的开发者工具。

官网地址：https://graphql.org/

中文网址(感觉不是官方的，连HTTPS都不是)：http://graphql.cn/

GraphQL来自Facebook，它于2012年开始开发，2015年开源。

GraphQL与编程语言无关，可以使用很多种语言/框架来构建Graph 服务器，包括.NET Core。

像Github，Pinterest，Coursera等公司都在使用GraphQL。

Github的API到目前有4个版本，第三个版本都是用的是REST，而第四个版本使用的是GraphQL。

GraphQL到底是什么？

这就是一个GraphQL查询的例子。左边是查询，右边是结果。

从这个例子可以看出，查询是可以嵌套的，所以使用GraphQL的客户端可以通过一次请求获得所有需要的数据。

每当对GraphQL服务器进行查询的时候，这些查询首先都会依据一个类型系统对其进行验证。每个GraphQL服务都会在GraphQL schema里定义类型信息。

可以把这个类型系统看作是你的API数据的蓝本，它由你定义的一系列对象所支撑。

例如这个User对象：

GraphQL经常被称作是一个：声明式数据获取语言。

GraphQL的设计原则

• 分层结构：GraphQL的查询是有层次结构的，字段可以内嵌其它字段；查询和返回数据的结构是一致的。
• 以产品中心：GraphQL是由客户端所需要的数据所驱动，语言和运行时也支持客户端。
• 强类型：GraphQL服务器由GraphQL类型系统所支撑。在schema里，每个数据点都有一个特定的类型，针对这个类型还有验证。
• 客户端定制查询：GraphQL服务器提供了可以让客户端进行定制查询的能力。
• 内省(introspective)：客户端可以查询GraphQL服务器的类型系(schema)。

为什么使用GraphQL？

谈起GraphQL，总是离不开REST。

如果您想了解REST in ASP.NET Core，请看我写的这个系列文章：https://www.cnblogs.com/cgzl/p/9178672.html#rest

REST有几个问题：

过度获取：REST里GET请求的查询结果通常比较大，并且超过了客户端的需求：

这里我只需要name，height，和mass，但是却返回了所有的字段。

而使用GraphQL，我只需要查询我需要的数据：

获取不足：使用REST时，我想获取部门和部门的人员，通常我需要先请求查询部门列表；然后遍历返回的部门列表，再次发出请求查询每个部门下的人员，所以是N+1查询。

而使用GraphQL，我就可以通过一个查询请求（嵌套的）取得相应的结果。

不灵活：随着API的演进，REST需要随时创建新的端点，所以REST API的端点增长速度很快；此外有版本和兼容性需要谨慎考虑。

而GraphQL，典型的结构是只有一个端点。这个单端点就像API网关一样组织了多个数据源，这样就会更简单。

综上，使用GraphQL的好处是：

• 避免多重REST请求
• 向下兼容，无需考虑版本
• 可以对现有的数据源(例如REST API)进行包装
• 与开发语言无关

GraphQL查询

我通过Github的GraphQL Explorer来进行演示，网址是：https://developer.github.com/v4/explorer/

登录之后，其效果如下：

Github使用了graphiql，graphiql是一个浏览器内的IDE，它可以用来浏览和查询GraphQL。

graphiql的网址是：https://github.com/graphql/graphiql。

下一篇文章，我也会在.NET项目里安装这个graphiql。

graphiql只是用来浏览查询GraphQL的一个浏览工具而已，其它比较流行的工具还包括GraphQL Playground 和 GraphQL Voyager等。

第一个查询

打开Github的GraphiQL以后，自动加载了一个查询语句，我们点击运行按钮，右侧就会返回查询的结果：

在这里，我查询了浏览者 viewer这个字段，当前浏览该网页的就是我自己；在查询里我还包括了viewer下的login字段，也就是登录名。

结果以JSON形式返回，其数据包含在data属性下，结构和查询结构一致。

如果我还想在查询中包含浏览者的姓名，那就加一个字段即可：

GraphQL的查询也可以有注释：

GraphiQL的智能提示

GraphiQL是具有智能提示的功能的。当你输入一个字母之后，就是这种效果：

如果你什么都不输入，还想知道有哪些字段，那么就按Alt+空格：

但是在windows上多少还是有些问题的，因为Alt+空格也会弹出浏览器的菜单