YeungYeah 的乱写地

GraphQL 入门

 Posts  

GraphQL 既是一种用于 API 的查询语言也是一个满足你数据查询的运行时。 GraphQL 对你的 API 中的数据提供了一套易于理解的完整描述，使得客户端能够准确地获得它需要的数据，而且没有任何冗余，也让 API 更容易地随着时间推移而演进，还能用于构建强大的开发者工具。

Why GraphQL

GraphQL 的出现主要是针对于传统的 REST API。传统的 REST API 使用资源实体的概念来划分各个数据实体，当我们需要请求数据的时候，我们往往需要发送多个请求来获取所需要的数据，一般来说，实体当中往往与其它不同类型的实体有着各样的关系。

例如我们需要展示各个用户所编写的博客文章，这需要获取博客的数据以及用户的数据。如果我们通过 REST API 获取，我们首先需要通过 GET /api/posts 获取所有的文章，返回的数据中就包含了文章的相关信息，如标题，内容，创建时间，以及作者的 id。根据获取的作者 id，我们需要根据每一个用户 id，发送请求 GET /api/users/:id 获取每个作者的信息。所以这样单一个展示页面，我们就可能需要发送大量的请求来获取数据。如果这个情况发生在需要数据现场渲染页面的网站，就比较尴尬，尤其是当网络情况较差时。

而使用 GraphQL 的话，只需要单个 Query 即可

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

query {
    posts {
        title,
        content,
        tags,
        date,
        user {
        	username,
          avatar,
          catchphrase,
          favorite_dog
        }
    }
}

另外传统的 API 在前后端进行接口交互时，往往需要文档来进行沟通交流，通过文档上面的定义和描述，来告诉前端接口到底长什么样，可以获取怎样的数据，以及怎样获取数据。然而文档的质量参差不齐，什么经常存在信息缺失的情况，尤其是需要人工编写的接口描述~~（给你写个类型信息和返回信息都不愿意）~~。尽管有着 Swagger 这些接口文档自动生成的工具，但是还是需要后端开发者付出额外的精力来添加描述信息。而如果写 GraphQL 的话，写一个 Scheme 就可以把支持的类型及其属性都清楚地暴露出去，只要再完善一下其中的 Query 以及 Mutation 内容，即可以把 GraphQL 支持的查询和更改操作都清楚地暴露出来。这些内容都可以通过算是内置的辅助工具 GraphiQL，进行文档的查询，以及实际的尝试。

How

to build

如何编写一个 GrahpQL 服务呢？我们首先需要定义好它的 Schema，包括其定义的类型（Type），输入类型（Input）。在 GraphQL 里面，服务能够支持的查询和更改操作，也是类型，分别是 Query 和 Mutation。

  • Type: 每个类型由多个属性组成，每个属性包含一个名字，以及该属性字段的类型，该类型可以为基本类型（Int, String, Boolean, Float, ID），数组，或者是自定义的对象类型
  • Input: 输入类型也是一个 Type
  • Query: 表示服务支持的查询内容，每个属性表示某个 query，其类型则为返回类型，可以接收参数
  • Mutation: 表示服务支持的更改操作，每个属性表示操作名，需要接收输入类型的参数，其类型为返回类型

以下为一个关于 todo 的 GraphQL Schema

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

type TodoItem {
    id: Int!
    title: String!
    content: String
    checked: Boolean!
    createdTime: String!
}

type Query {
    todoItems: [TodoItem]
    todoItem(id: Int!): TodoItem
}

input TodoItemInput {
  title: String!
  content: String
  checked: Boolean!
  createdTime: String!
}

type Mutation {
    createTodoItem(todo: TodoItemInput!): TodoItem
    updateTodoItem(id: Int!, todo: TodoItemInput!): TodoItem
}

to use

怎么使用 GraphQL 服务呢？

Query

需要查询数据时，我们只需要通过花括号把需要的类型和字段的列举出来即可。当需要传入变量，我们可以在 query 处进行定义，然后在变量处进行值传递。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

query {
  TodoItem {
    title
    content
  }
}

# or

query ($id: Int!) {
  todoItem(id: $id) {
    id
    title
  }
}

# variables
{
  "id": 1
}

Mutation

进行数据更改时，也是类似，传入变量，调用相应的 mutation 方法即可，另外根据需要，我们还可以选择返回的属性。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

mutation ($todo:TodoItemInput!){
  createTodoItem(todo:$todo) {
    id
    title
    content
  }
}

# variables
{
  "todo": {
  	"title": "asdafa",
    "content": "asdaf",
    "createdTime": "today",
    "checked": false
  }
}

to implement

怎样快速搭一个 GraphQL 服务出来呢？当然是采用动态语言最快了，而其中，又自然是选择使用 GraphQL 最多的 JavaScript 语言实现起来最快。

这里我们使用 express 来提高 http 服务，使用 express-graphql 来搭建 GraphQL 服务

1

npm install --save express express-graphql graphql

然后就是一把梭地实现，首先构建 GraphQL Schema，然后搭建 http 服务，构建并绑定一个 GraphQL handler，启动服务，完。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

var express = require('express');
var { graphqlHTTP } = require('express-graphql');
var { buildSchema } = require('graphql');

var schema = buildSchema(``) // 内容省略

// 那个数组假装一下数据库
const todoItemDb = []

var root = {// 这里用来存储各个 query 和 mutation 的响应函数
  todoItems: () => todoItemDb,
  todoItem: ({id}) => {
    for(let todo of todoItemDb) {
        if(todo['id'] == id) return todo
    }

    return {}
  },
  createTodoItem: ({todo}) => {
      todo['id'] = todoItemDb.length
      todoItemDb.push(todo)
      console.log(todo)
      return todo
  },
  updateTodoItem: ({id, todo}) => {
    for(let i=0;i<todoItemDb.length;i++) {
        if(todoItemDb[i]['id']== id) {
            todo['id'] = id
            todoItemDb[i] = todo
            return todo
        }
    }
  }
}

var app = express();

app.use('/graphql', graphqlHTTP({
  schema: schema,
  rootValue: root,
  graphiql: true,
}));
app.listen(4000);

实现就这么简单 2333

后记

在写这篇博客的时候，其实写到后面有点点迷茫，所谓的 GraphQL 真的是这么好吗？如果真的这么好，为什么当前主流的前后端分离，后端接口的方式还是用传统方式的类 RESTful API 的方式来设计和实现呢？

其实回过头看上面举出的例子，那些所谓的需要多次请求才获取到的数据，其实本质上也是因为后端考虑要获取多个数据，才将其整合在一起，作为一个新的独立的 endpoint 来暴露出来的。换句话，其实传统的 API 也可以做到，只需要再写一个 endpoint，专门为这个情况设置独立的 handler。

不过这种专门设置一个新的 endpoint 也未免太过不够 elegant，而且 GraphQL 对我这种还没经历过实际项目的新手来说，最大的优点，还是其自带的 GraphiQL 吧，一个带 ui 的 playground 提供给使用者来了解 API 中支持的类型，查询和变更操作，并且可以随时进行尝试，实在吸引。

所以以后如果需要到 GitHub 挖点数据的时候，不妨把请求方式从其传统的 REST API 上搬到 GraphQL 当中。这样就不需要再在命令行或者是 Postman 的方式来发请求尝试，直接在网页端界面解决。

相关文章：