GraphQL ----A data query language#

GraphQL是什么？#

GraphQL是Facebook创建的API格式。以下是从官方网页引用的内容。

GraphQL是一种用于API的查询语言，它是用服务器端运行环境来执行查询的，通过定义的类型系统来对数据进行查询

为什么需要Graphql？#

客户端决定结果——————————无论是rest异或是rpc,都是由服务端定义请求的参数和返回的响应，比如请求用户信息，可能有简单的直接请求用户的name与avater,也可能会有请求用户的详细信息，如果要实现相应的功能，可能我们会要分成两个路由或者请求中带有0值来不做处理，返回时分开返回或者不请求的返回0值，如果在大型应用中，这种的处理方法无疑会让整体变得臃肿且复杂。 GraphQL 中，查询的规范是在客户端编码而不是在服务器端。这些查询是以字段级别的粒度指定的，GraphQL 查询精确地返回客户端所请求的内容，不多也不少。
天生具有高版本兼容————————在打造产品尤其是移动端应用时，经常会有多版本共存的情况，如果是使用rest+json的形式的话，新版本的更新可能会导致某些接口出现破坏性的改变，进而导致需要单独维护旧版本的接口，造成运维方面的困难。客户端指定的查询简化了管理我们的向后兼容保证
分层结构：当今大多数产品开发都涉及视图层次结构的创建和操作。为了与应用的结构保持一致，GraphQL 查询本身就是一个分层的字段集合。查询的形状就像它返回的数据一样。这是一种产品工程师描述数据需求的自然方式。
强类型：GraphQL 是强类型的。给定一个查询，工具可以在执行前确保该查询在语法上正确且在 GraphQL 类型系统中有效，即在开发时间，服务器也可以对响应的形状和性质做出某些保证。这使得构建高质量的客户端工具更加容易。

GraphQL的几个重要概念#

type(类型系统)：用来定义返回的数据类型

1
#基本类型：
2
Int     # 整数
3
Float   # 浮点数
4
String  # 字符串
5
Boolean # 布尔
6
ID      # 唯一标识符
7
#结构体
8
type User {
9
  id: ID!
10
  name: String!
11
  age: Int
12
}!表示非空

query(查询)：可以类比成restful的请求结构体或者query等，只不过这个是由客户端决定,只取需要的字段，避免 REST 的“过多或过少数据”问题

1
query {
2
  user(id: 1) {
3
    name
4
    age
5
  }
6
}
7
{
8
  "data": {
9
    "user": {
10
      "name": "Alice",
11
      "age": 25
12
    }
13
  }
14
}

Mutation(变更)：用于修改数据（增删改）

1
mutation {
2
  createUser(input: {name: "Bob", age: 20}) {
3
    id
4
    name
5
  }
6
}
7
{
8
  "data": {
9
    "createUser": {
10
      "id": "2",
11
      "name": "Bob"
12
    }
13
  }
14
}

reslover(解析器)，这里一般就是核心逻辑，比如从数据库查询数据等。

1
const resolvers = {
2
  Query: {
3
    user: (parent, args, context) => {
4
      return db.getUserById(args.id)
5
    }
6
  }
7
}

schema(蓝图)整合了query和mutation，如果将mvc的service看作mutation，schema就有点像router。定义 API 的数据结构、类型系统和可操作的接口

1
schema {
2
  query: Query
3
  mutation: Mutation
4
}

Subscription(订阅):实现实时更新(如聊天室、股票行情等),应该是用在websocket中，还没太用过

1
subscription {
2
  messageAdded {
3
    id
4
    content
5
    author {
6
      name
7
    }
8
  }
9
}

下面来看看在go语言中怎么使用吧，目前比较热门的包分别是gqlgen与graphql-go，其中gqlgen更自动化，用起来更顺手，graphql-go比较底层，很多东西需要自己写。

1
//graphql-go
2
package main
3

4
import (
5
  "encoding/json"
6
  "log"
7
  "net/http"
8

9
  "github.com/graphql-go/graphql"
10
)
11

12
type User struct {
13
  ID   string `json:"id"`
14
  Name string `json:"name"`
15
  Age  int    `json:"age"`
16
}
17

18
// 模拟数据库
19
var users = []User{
20
  {ID: "1", Name: "Alice", Age: 23},
21
  {ID: "2", Name: "Bob", Age: 25},
22
}
23

24
func main() {
25
  // 定义 GraphQL Object Type：User
26
  userType := graphql.NewObject(graphql.ObjectConfig{
27
    Name: "User",
28
    Fields: graphql.Fields{
29
      "id":   &graphql.Field{Type: graphql.NewNonNull(graphql.String)},
30
      "name": &graphql.Field{Type: graphql.NewNonNull(graphql.String)},
31
      "age":  &graphql.Field{Type: graphql.Int},
32
    },
33
  })
34

35
  // 定义 Query
36
  rootQuery := graphql.NewObject(graphql.ObjectConfig{
37
    Name: "Query",
38
    Fields: graphql.Fields{
39
      "users": &graphql.Field{
40
        Type: graphql.NewList(userType),
41
        Resolve: func(p graphql.ResolveParams) (interface{}, error) {
42
          return users, nil
43
        },
44
      },
45
      "user": &graphql.Field{
46
        Type: userType,
47
        Args: graphql.FieldConfigArgument{
48
          "id": &graphql.ArgumentConfig{
49
            Type: graphql.NewNonNull(graphql.String),
50
          },
51
        },
52
        Resolve: func(p graphql.ResolveParams) (interface{}, error) {
53
          id := p.Args["id"].(string)
54
          for _, u := range users {
55
            if u.ID == id {
56
              return u, nil
57
            }
58
          }
59
          return nil, nil
60
        },
61
      },
62
    },
63
  })
64

65
  // 定义 Mutation
66
  rootMutation := graphql.NewObject(graphql.ObjectConfig{
67
    Name: "Mutation",
68
    Fields: graphql.Fields{
69
      "createUser": &graphql.Field{
70
        Type: userType,
71
        Args: graphql.FieldConfigArgument{
72
          "name": &graphql.ArgumentConfig{
73
            Type: graphql.NewNonNull(graphql.String),
74
          },
75
          "age": &graphql.ArgumentConfig{
76
            Type: graphql.Int,
77
          },
78
        },
79
        Resolve: func(p graphql.ResolveParams) (interface{}, error) {
80
          name := p.Args["name"].(string)
81
          age, _ := p.Args["age"].(int)
82
          user := User{
83
            ID:   string(rune(len(users) + 1)),
84
            Name: name,
85
            Age:  age,
86
          }
87
          users = append(users, user)
88
          return user, nil
89
        },
90
      },
91
    },
92
  })
93

94
    // 构建 Schema
95
  schema, err := graphql.NewSchema(graphql.SchemaConfig{
96
    Query:    rootQuery,
97
    Mutation: rootMutation,
98
  })
99
  if err != nil {
100
    log.Fatalf("创建 Schema 失败: %v", err)
101
  }
102

103
  // 创建 GraphQL handler（带 playground）
104
  h := handler.New(&handler.Config{
105
    Schema:   &schema,
106
    Pretty:   true,
107
    GraphiQL: true, // 打开 GraphQL Playground
108
  })
109
  // 注册路由
110
  http.Handle("/graphql", h)
111

112
  log.Println("GraphQL server running at http://localhost:8080/graphql")
113
  log.Fatal(http.ListenAndServe(":8080", nil))
114
}

由于swag并不直接支持graphql，所以我们使用了GraphiQL，这是一个web的ide工具吧，可以帮助我们去执行graphql的各种服务并测试，也方便前后端的对接。我找到一种用SpectaQL来生成文档的方法(但感觉不如原生的，只是看着方便点)。

1
npm install -g spectaql #安装工具

创建.yml文件

1
title: "GraphQL API"
2
description: "自动生成的 GraphQL 文档"
3
logoUrl: ""
4
introspection:
5
  url: "http://localhost:8080/graphql"//可以用。graphql文件代替
6
servers:
7
  - url: "http://localhost:8080/graphql"  # GraphQL 服务地址
8
build:
9
  outputDir: "docs"

1
spectaql xxx.yml#这会生成对应得html

日后有时间可以研究一下这篇文章Swag与GraphQL：混合API文档生成解决方案-CSDN博客

下面我们来看看gqlgen:

使用gqlgen，我们不需要去操心那复杂的组装逻辑，只需要定义方法与数据结构并实现方法，其余的事情都会通过ast插桩映射帮你完成，首先我们需要创建一个gqlgen.yml和schema.graphqls

1
schema:
2
  - graph/schema.graphqls
3

4
exec:
5
  filename: graph/generated/generated.go
6
  package: generated
7

8
model:
9
  filename: graph/model/models_gen.go
10
  package: model
11

12
resolver:
13
  layout: follow-schema
14
  dir: graph
15
  package: graph

1
type User {
2
    id: ID!
3
    name: String!
4
    age: Int!
5
}
6

7
type Query {
8
    users: [User!]
9
    user(id: ID!): User
10
}
11

12
type Mutation {
13
    createUser(name: String!,age: Int!) :User!
14
}

然后运行

1
 go run github.com/99designs/gqlgen generate

下面是一个示例main文件

1
package main
2

3
import (
4
  "github.com/99designs/gqlgen/graphql/handler/transport"
5
  "gragen-ex/graph"
6
  "gragen-ex/graph/generated"
7
  "log"
8
  "net/http"
9

10
  "github.com/99designs/gqlgen/graphql/handler"
11
  "github.com/99designs/gqlgen/graphql/playground"
12
)
13

14
const defaultPort = "8080"
15

16
func main() {
17
  port := defaultPort
18

19
  // 创建 GraphQL server
20
  srv := handler.New(generated.NewExecutableSchema(generated.Config{
21
    Resolvers: &graph.Resolver{},
22
  }))
23
  srv.AddTransport(transport.POST{}) // 支持 POST 请求
24
  srv.AddTransport(transport.GET{})  // 支持 GET 请求（query string）
25
  srv.AddTransport(transport.Websocket{})
26
  http.Handle("/graphql", srv)
27
  http.Handle("/", playground.Handler("GraphQL Playground", "/graphql"))
28

29
  log.Printf("connect to http://localhost:%s/ for GraphQL playground", port)
30
  log.Fatal(http.ListenAndServe(":"+port, nil))
31
}