专栏首页草根专栏使用ASP.NET Core开发GraphQL服务器 -- 预备知识(上)

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

其实前面那个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,仔细看一下那些和字段在一起的黄色字体的东西:

这些就是类型

在类型里,有的是常见的类型:例如StringIntFloatBooleanID

输入类型和返回类型

当定义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里使用的非常多

今天先到这。

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 使用ASP.NET Core支持GraphQL -- 较为原始的方法

    下面是GraphQL的定义:  GraphQL 既是一种用于 API 的查询语言也是一个满足你数据查询的运行时。 GraphQL 对你的 API 中的数据提供了...

    solenovex
  • 使用VS Code开发asp.net core (上)

    本文是基于Windows10的. 下载地址: https://code.visualstudio.com/ insider 版下载地址: https://cod...

    solenovex
  • Git -- Rebase

    git rebase: 这个命令可以把一个分支上commit的变化放到另一个分支上重新上演一遍. ? ? ? 简单的Rebase例子. 首先准备好一个git项目...

    solenovex
  • 会优化,你真的会优化吗?其实你可能真的缺少一份理解【数据库篇】

      其实,在写这篇博客之前,我也是感觉自己会点优化,至少知道不要使用“*”号啊,给经常查询的列创建索引啊什么的,其实都不是大家想的那样简单的,其实它们背后存在很...

    赵小忠
  • 刷题第3篇:重复字符串的删除

    给你一个字符串 s,「k 倍重复项删除操作」将会从 s 中选择 k 个相邻且相等的字母,并删除它们,使被删去的字符串的左侧和右侧连在一起。你需要对 s 重复进行...

    鹏-程-万-里
  • 史上最详细的 MongoDB4.0搭建分布式集群(亲测有效)

    版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。

    拓荒者
  • GEOquery包的getGEO函数总是无法下载肿么办

    解决方式也简单,加上代码: options( 'download.file.method.GEOquery' = 'libcurl' ) 即可!

    生信技能树
  • 自制小工具大大加速MySQL SQL语句优化(附源码)

    优化SQL,是DBA常见的工作之一。如何高效、快速地优化一条语句,是每个DBA经常要面对的一个问题。在日常的优化工作中,我发现有很多操作是在优化过程中必不可少的...

    宜信技术学院
  • 分布式作业系统 Elastic-Job-Lite 源码分析 —— 作业分片策略

    JobShardingStrategy,作业分片策略接口。分片策略通过实现接口的 #sharding(...) 方法提供作业分片的计算。

    芋道源码
  • 你真的知道如何优化SQL么?

    虽然使用Explain不能够马上调优我们的SQL,它也不能给予我们一些调整建议,但是它能够让我们了解MySQL 优化器是如何执行SQL 语句的

    Java学习录

扫码关注云+社区

领取腾讯云代金券