GraphQL(Graph Query Language)即图形化查询语言。使用GraphQL,可以将所有的业务建模为图。图是将很多真实世界现象变成模型的强大工具,因为它们和我们自然的心智模型和基本过程的口头描述很相似。通过GraphQL,可以把我们的业务领域通过定义schema建模成一张图;在Schema中,可以定义不同类型的节点,以及他们之间是如何连接的。在客户端这边,这创建了一种类似面向对象编程的模式:引用其他类型的类型。在服务端,由于GraphQL定义了接口,你可以在任何后端自由的使用它。
GraphQL中的类型主要分为一下几种:
-
对象类型(Object Types)
一个 GraphQL schema 中的最基本的组件是对象类型,它就表示你可以从服务上获取到什么类型的对象,以及这个对象有什么字段。在graphQL.Net中,对应的类型是ObjectGraphType. -
标量类型(Scalar Types)
标量类型没有任何次级字段,它们是查询的叶子节点。GraphQL自带一组默认标量类型:
Int:有符号32位整数。
Float:有符号双精度浮点值。
String:UTF-8字符序列。
Boolean:true或者false。
ID:ID标量类型表示一个唯一标识符,通常以重新获取对象或者作为缓存中的键。
ID类型使用和String一样的方式序列化;然而将其定义为ID意味着并不需要人类可读型。
GraphQL的net版本中这些类型的对应关系如下:
GraphQL类型 | GraphQL.Net实现类型 | AspNet类型 |
---|---|---|
Int | IntGraphType | int |
Float | FloatGraphType | float |
String | StringGraphType | string |
Boolean | BooleanGraphType | bool |
Id | IdGraphType | string |
除了这些类型外,我们还可以自定义标量类型。标量类型在GraphQL.Net中的基类是ScalarGraphType。继承ScalarGraphType并实现其抽象方法其序列化、反序列化和验证即可。GraphQL.Net本身帮我们实现了更多标量:DecimalGraphType、DateTimeGraphType、DateGraphType、ByteGraphType、UriGraphType等很多常用的标量类型。
-
枚举类型(Enumeration Types)
枚举类型是一种特殊的标量,它限制在一个特殊的可选值集合内。枚举类型对应GraphQL.Net中的EnumerationGraphType,对应AspNet中的Enum类型。 -
表和非空类型(Lists and Not-Null)
对象类型、标量以及枚举是 GraphQL 中你唯一可以定义的类型种类。但是当你在 schema 的其他部分使用这些类型时,或者在你的查询变量声明处使用时,你可以给它们应用额外的类型修饰符来影响这些值的验证。列表在GraphQL文档中的规范是通过中括号[]表示。例如[Test]代表的就是返回类型为Test的列表。在GraphQL.Net中的类型是ListGraphType,对应AspNet中的List。
非空类型在GraphQL文档中的规范是通过感叹号!表示。例如Test!代表的是这个类型不能为空。在GraphQL.Net中的类型是NonNullGraphType。如果要表示一个字段非空,还可以通过如下语句实现:
Field(x => x.id,nullable:false).Description("Id");
-
接口(Interfaces)
一个接口是一个抽象类型,它包含某些字段,而对象类型必须包含这些字段,才能算实现了这个接口。接口在GraphQL.Net中对应的类型是InterfaceGraphType。 -
联合类型(Union Types)
联合类型和接口十分相似,但是它并不指定类型之间的任何共同字段,联合类型在GraphQL.Net中对应的类型是UnionGraphType。 -
输入类型(Input Types)
目前为止,我们只讨论过将例如枚举和字符串等标量值作为参数传递给字段,但是你也能很容易地传递复杂对象。这在变更(mutation)中特别有用,因为有时候你需要传递一整个对象作为新建对象。在 GraphQL schema language 中,输入对象看上去和常规对象一模一样,除了关键字是 input 而不是 type。输出类型在GraphQL.Net中对应的类型是InputObjectType。
类型实例:
传统的Model:
public class Student
{
public int id { get; set; }
public string name { get; set; }
public int score { get; set; }
}
GraphQL的对象类型的定义:
public class StudentOutputGraphType:ObjectGraphType<Student>
{
public StudentOutputGraphType()
{
Description = "学生信息输出类型";
Field(x => x.id,nullable:true).Description("Id");
Field(x => x.name).Description("姓名");
Field(x => x.score).Description("分数");
}
}
GraphQL Input类型的定义:
public class StudentInputGraphType:InputObjectGraphType<Student>
{
public StudentInputGraphType()
{
Description = "学生信息输入类型";
Field(x => x.name).Description("姓名");
Field(x => x.score).Description("分数");
}
}
对象类型、输入类型、列表和非空类型就已经能完成基本的操作了。内置的标量类型一般也够用了。返回特定最小原子对象的时候,可能会需要生成自定义的标量。这几种GraphQL类型与AspNet的类型转换主要是通过Net的GraphQL引擎去完成的。下一节将讲述GraphQL引擎的转换过程。