GraphQL简介及入门

1、什么是GraphQL?

GraphQL 是由 Facebook 创造的用于描述复杂数据模型的一种查询语言。这里查询语言所指的并不是常规意义上的类似 sql 语句的查询语言，而是一种用于前后端数据查询方式的规范。官网（中文）：https://graphql.cn/；规范地址：http://spec.graphql.cn/。
在这里插入图片描述

2、RESTful存在的问题

RESTful是我们已经很熟悉的用于api通信的规范，如这样：

GET http://127.0.0.1/user/1 #查询
POST http://127.0.0.1/user #新增
PUT http://127.0.0.1/user #更新
DELETE http://127.0.0.1/user #删除

在查询的时候，往往是这样：

#请求
GET http://127.0.0.1/user/1
#响应：
{
 id : 1,
 name : "张三",
 age : 20,
 address : "北京市",
 ……
}

这样似乎是没有问题的，如果，对于这次请求，我只需要id和name属性，其他的属性我都不需要，如果我依然拿到的是全部的属性，这是不是一种资源浪费？还有这样的一种场景，就是一次请求不能满足需求，需要有多次请求才能完成，像这样：

#查询用户信息
GET http://127.0.0.1/user/1
#响应：
{
 id : 1,
 name : "张三",
 age : 20,
 address : "北京市",
 ……
}
#查询用户的证件信息
GET http://127.0.0.1/card/8888
#响应：
{
 id : 8888,
 name : "张三",
 cardNumber : "666666666666",
 address : "北京市",
}

查询用户以及他的信息，需要进行2次查询才能够完成，这样对于前端等接口的使用方是很不友好的，试想一下，如果查询信息有10个，是不是要发起10次请求才能完成？

3、了解GraphQL优势

GraphQL很好的解决了RESTful在使用过程中的不足，接下来，我们进一步了解下它。

3.1、按需索取数据，避免浪费

示例地址：http://graphql.cn/learn/schema/#type-system
在这里插入图片描述

可以看出，当请求中只有name属性时，响应结果中只包含name属性，如果请求中添加appearsIn属性，那么结果中就会返回appearsIn的值。

3.2、一次查询多个数据

在这里插入图片描述
可以看到，一次请求，不仅查询到了hero数据，而且还查询到了friends数据。节省了网络请求次数。

3.3、API的演进无需划分版本

在这里插入图片描述

4、GraphQL查询的规范

GraphQL定义了一套规范，用来描述语法定义，具体参考：http://graphql.cn/learn/queries/

4.1、字段（Fields）

在GraphQL的查询中，请求结构中包含了所预期结果的结构，这个就是字段。并且响应的结构和请求结构基本一致，这是GraphQL的一个特性，这样就可以让请求发起者很清楚的知道自己想要什么。
在这里插入图片描述

4.2、参数（Arguments）

在查询数据时，离不开传递参数，在GraphQL的查询中，也是可以传递参数的，语法：(参数名:参数值)
在这里插入图片描述

4.3、别名（Aliases）

如果一次查询多个相同对象，但是值不同，这个时候就需要起别名了，否则json的语法就不能通过了。比如这样：
在这里插入图片描述

4.4、片段（Fragments）

查询对的属相如果相同，可以采用片段的方式进行简化定义。
在这里插入图片描述

5、GraphQL的Schema 和类型规范

Schema 是用于定义数据结构的，比如说，User对象中有哪些属性，对象与对象之间是什么关系等。参考官网文档：http://graphql.cn/learn/schema/

5.1、Schema定义结构

schema {  #定义查询
 query: UserQuery
}
type UserQuery { #定义查询的类型
 user(id:ID) : User #指定对象以及参数类型
}
type User { #定义对象
 id:ID! # !表示该属性是非空项
 name:String
 age:Int
}

5.2、标量类型（Scalar Types）

GraphQL规范中，默认定义了5种类型：
Int ：有符号 32 位整数。
Float ：有符号双精度浮点值。
String ：UTF‐8 字符序列。
Boolean ： true 或者 false 。
ID ：ID 标量类型表示一个唯一标识符，通常用以重新获取对象或者作为缓存中的键。
规范中定义的这5种类型，显然是不能满足需求的，所以在各种语言实现中，都有对类型进行了扩充，也就是GraphQL支持自定义类型，比如在graphql-java实现中增加了：Long、Byte等。

5.3、枚举类型

枚举类型是一种特殊的标量，它限制在一个特殊的可选值集合内。

enum Episode { #定义枚举
NEWHOPE
EMPIRE
JEDI
}
type Human {
 id: ID!
 name: String!
 appearsIn: [Episode]! #使用枚举类型
 homePlanet: String
}

5.4、接口（interface）

跟许多类型系统一样，GraphQL 支持接口。一个接口是一个抽象类型，它包含某些字段，而对象类型必须包含这些字段，才能算实现了这个接口。例如，你可以用一个 Character 接口用以表示《星球大战》三部曲中的任何角色：

interface Character {  #定义接口
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
}
#实现接口
type Human implements Character {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
starships: [Starship]
totalCredits: Int
}
type Droid implements Character {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
primaryFunction: String
}

6、GraphQL的Java实现

通过前面的讲解，我们对GraphQL有了解，官方只是定义了规范并没有做实现，就需要有第三方来进行实现了，关于GraphQL的java实现有几种，我们选择使用官方推荐的实现：graphql-java，我们通过该实现就可以编写GraphQL的服务端了。
官网：https://www.graphql-java.com/
github：https://github.com/graphql-java/graphql-java
在这里插入图片描述

6.1、入门示例

导入依赖：
graphql-java包并没有发布到maven中央仓库，需要配置第三方仓库才能使用。

<dependency>
  <groupId>com.graphql-java</groupId>
  <artifactId>graphql-java</artifactId>
  <version>11.0</version>
</dependency>

在setting.xml文件里进行配置：

<profile>
 <id>bintray</id>
 <repositories>
  <repository>
   <id>bintray</id>
   <url>http://dl.bintray.com/andimarek/graphql-java</url>
   <releases>
    <enabled>true</enabled>
   </releases>
   <snapshots>
    <enabled>false</enabled>
   </snapshots>
  </repository>
 </repositories>
 <pluginRepositories>
  <pluginRepository>
   <id>bintray</id>
   <url>http://dl.bintray.com/andimarek/graphql-java</url>
   <releases>
    <enabled>true</enabled>
   </releases>
   <snapshots>
    <enabled>false</enabled>
   </snapshots>
  </pluginRepository>
 </pluginRepositories>
</profile>

创建User对象

public class User {
private Long id;
  private String name;
  private Integer age;
  public User() {
 }
  public User(Long id, String name, Integer age) {
    this.id = id;
    this.name = name;
    this.age = age;
 }
  public Long getId() {
    return id;
 }
  public void setId(Long id) {
    this.id = id;
 }
  public String getName() {
    return name;
 }
  public void setName(String name) {
    this.name = name;
 }
  public Integer getAge() {
    return age;
 }
  public void setAge(Integer age) {
    this.age = age;
 }
}

编写查询User对象实现

#对应的User定义如下
schema {  #定义查询
 query: UserQuery
}
type UserQuery { #定义查询的类型
 user : User #指定对象以及参数类型
}
type User { #定义对象
 id:Long! # !表示该属性是非空项
 name:String
  age:Int
}

Java实现：

import graphql.ExecutionResult;
import graphql.GraphQL;
import graphql.schema.GraphQLFieldDefinition;
import graphql.schema.GraphQLObjectType;
import graphql.schema.GraphQLSchema;
import graphql.schema.StaticDataFetcher;
import static graphql.Scalars.*;
import static graphql.schema.GraphQLFieldDefinition.newFieldDefinition;
import static graphql.schema.GraphQLObjectType.newObject;
public class GraphQLDemo {
  /**
  * 定义Schema
  * <p>
  * schema { #定义查询
  *   query: UserQuery
  * }
  *
  * @return
  */
  public static GraphQLSchema createGraphqlSchema(GraphQLFieldDefinition
userDefinition) {
    GraphQLObjectType userQuery = newObject().name("userQuery")
       .field(userDefinition).build();
    return GraphQLSchema.newSchema().query(userQuery).build();
 }
  /**
  * 定义查询的类型
  * <p>
  * type UserQuery { #定义查询的类型
  *   user : User #指定对象
  * }
  *
  * @return
  */
  public static GraphQLFieldDefinition createUserDefinition(GraphQLObjectType
userType) {
    return newFieldDefinition()
       .name("User")
       .type(userType)
        //静态数据
       .dataFetcher(new StaticDataFetcher(new User(1L, "张三", 20)))
       .build();
 }
  /**
  * 定义User对象类型
  *
  * type User { #定义对象
  *   id:Long! # !表示该属性是非空项
  *   name:String
  *   age:Int
  * }
  *
  *
  * @return
  */
  public static GraphQLObjectType createUserObjectType(){
    return newObject()
       .name("User")
       .field(newFieldDefinition().name("id").type(GraphQLLong))
       .field(newFieldDefinition().name("name").type(GraphQLString))
       .field(newFieldDefinition().name("age").type(GraphQLInt))
       .build();
 }
  public static void main(String[] args) {
    GraphQLObjectType userObjectType = createUserObjectType();
    GraphQLFieldDefinition userDefinition =
createUserDefinition(userObjectType);
    GraphQL graphQL =
GraphQL.newGraphQL(createGraphqlSchema(userDefinition)).build();
    String query = "{User{id,name}}";
    ExecutionResult executionResult = graphQL.execute(query);
    // 打印错误
    System.out.println("错误：" + executionResult.getErrors());
    // 打印数据
    System.out.println("结果：" +(Object) executionResult.getData());
 }
}

运行结果：

查询字符串：{User{id,name,age}}
错误：[]
结果：{User={id=1, name=张三, age=20}}
---------------
查询字符串：{User{id,name}}
错误：[]
结果：{User={id=1, name=张三}}

设置查询参数修改createUserDefinition()方法：

public static GraphQLFieldDefinition createUserDefinition(GraphQLObjectType
userType) {
    return newFieldDefinition()
       .name("User")
       .type(userType)
        //静态数据
     //  .dataFetcher(new StaticDataFetcher(new User(1L, "张三", 20)))
        // 设置参数
       .argument(newArgument().name("id").type(GraphQLLong).build())
       .dataFetcher(environment -> {
          Long id = environment.getArgument("id");
          return new User(id, "张三_"+id, 20 + id.intValue());
       })
       .build();
 }

结果：

查询字符串：{User(id:1){id,name}}
错误：[]
结果：{User={id=1, name=张三_1}}
----------------
查询字符串：{User(id:1){id,name,age}}
错误：[]
结果：{User={id=1, name=张三_1, age=21}}

6.2、使用SDL构建schema

graphql-java 提供了两种不同的方式来定义模式：以编程方式作为Java代码或通过特殊的graphql dsl（称为SDL）。

创建user.graphqls文件
在resources目录下创建user.graphqls文件：

schema {
 query: UserQuery
}
type UserQuery {
 user(id:Long) : User
}
type User {
 id:Long!
 name:String
 age:Int
}

安装GraphQL插件：