使用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，请看我写的这个系列文章：http://www.javashuo.com/article/p-rqwpmfqu-gm.html

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+空格也会弹出浏览器的菜单😭。。。。

 

其实前面那个query关键字在这里是能够省略的，点击prettify以后，就会把query关键字去掉；而且若是您的查询格式比较乱的话，点击prettify也会对查询进行格式化：

 

查询参数

 在GraphQL里，每一个字段均可以有本身的参数。

 直接看例子。下面这个例子里，我想查询登陆名为facebook的仓库全部者：

括号里就是查询参数，这个参数的做用就是过滤数据，返回login字段等于facebook的仓库全部者。

 

再看一个例子，此次我要查询repository，参数是name，参数值是graphql，点击查询：

注意，查询语句里有红色波浪线。不出意外，返回的了错误。

（全部的错误请求的返回结果都是这个格式的）。

 

错误信息里告诉咱们要查询repository这个字段，必需要提供owner这个参数，那么咱们就加上这个参数：

此次终于返回了正确的结果。

 

也能够再添加几个字段：

 

GraphQL Schema

上面我介绍了几个查询的例子，下面我介绍一下这个查询的后台工做原理。

上面这些字段的设定是由GraphQL的schema来决定的。

• Schema提供了你的数据中全部使用的对象类型。
• 它制定了全部值的类型。

 

打开Github的Graphiql，右侧有个Docs按钮，也就是文档：

每当咱们定义了一个schema以后，文档就会自动生成。

 

打开Docs，能够看到两种操做类型：

• Query，查询，也就是用来获取数据的。
• Mutation，变化，也就是用来更新数据的。

 

点击Query，进去后咱们能够在这里看见以前进行的那些查询：

 

那么就点击一下刚才的repository这个查询：

能够看到这个查询须要两个参数：owner和name，类型都是字符串。

 

再返回到Query，仔细看一下那些和字段在一块儿的黄色字体的东西：

这些就是类型。

在类型里，有的是常见的类型：例如String，Int，Float，Boolean，ID。

 

输入类型和返回类型

当定义schema的时候，咱们也会相应的定义所容许的输入类型，它们能够是参数类型或字段类型。

输入类型能够是：Int，Float，String，Boolean，Null，Enum，List，Object。

例如：

后边的叹号，表示该参数是必须的。

 

冒号后边的部分就是返回类型

 

当咱们定义好Schema以后，文档就生成了，因此GraphQL是自我生成文档的。

 

查询Schema

除了看文档以外，你能够直接查询schema，这点在咱们不使用graphiql的时候尤为有用。

这个查询里，咱们要查的是__schema字段；而后是它下面的queryType字段，queryType将会返回schema下全部的查询；而后我再查询queryType下的name和description，点击运行，就会看到右边的结果：name是Query，描述是它是Github GraphQL接口的query root。

这个结果和文档里的描述是同样的：

下面再加上fields字段看看：

这个结果的fields字段就包括不少内容了：codeOfConduct，license等等。而这些就是root query全部支持的字段。

 

查询Type

除了查询schema外，另外一个有用的查询就是Type的查询。

例子，查询Repository这个类型的相关信息，查询__type字段，带着参数name为Repository：

这个查询结果也和文档里的一致，我就不贴图了。

 

别名

当我使用不一样的参数来查询两个一样的字段的时候，会报错的：

 

时就应该使用别名了。添加别名只须要在字段前边加上别名和冒号便可：

这回查询就没有错误了。

 

Fragment

上面的例子里，graphql和aspnethome都查询的是相同的几个字段。这样的输入就有点重复了，这时咱们就可使用Fragment。Fragement是可重用的字段集合，它能够根据须要被包含在查询里。

上面的例子使用fragement之后就是这样：

最下面是fragment的定义，使用fragment关键字，而后跟着自定义的名称，它做用于Repository这个类型，大括号里就是须要查询的字段。

在查询里使用fragment时须要用三个点"..."，它的做用至关于js里的展开操做符，把fragment里面的字段展开到相应的查询里。

fragment在GraphQL里使用的很是多。

 

今天先到这。