GraphQL是用于API的查询语言，定义了客户端与服务端之间查询的规范，主要的特性是客户端可以自己决定要获取哪些字段、获取多种资源时只需发送一次请求。GraphQL 规范于 2015 年开源，现在已经9102年，许多语言都有关于GraphQL规范实现，并且网上随手一搜就有一大堆关于它的文章，不过还是只有亲自实践才能体会这门语言的好处。

相关文章

• GraphQL学习：入门
• GraphQL学习：分页
• GraphQL学习：接口、联合类型、输入类型

目录

• 学习背景
• 使用koa2搭建GraphQL服务
• GraphQL客户端
• 使用GraphQL实现CRUD

学习背景

目前的项目后端使用的微服务架构，在PC端上调用接口时，通常会有一个对象几十个字段的情况，并且需要访问多个微服务的接口来获取数据。而对于将要开发的移动端，减少无用字段和请求是优化性能的关键，如果后端微服务为移动端重新开发接口是非常浪费时间的，并且通常微服务之间是不能进行跨服务查询的。考虑到这正是GraphQL的最佳使用场景，因此希望通过GraphQL的学习和类似的场景的实践探索一下GraphQL的可行性以及实用性。即使当前项目不会用到，也是良好的学习体验了。

后续学习内容主要如下：

• 通过官方文档熟悉GraphQL标准（本文章不对此做介绍），地址：https://graphql.cn/learn/
• 使用koa2框架入门GraphQL，包括服务搭建、客户端请求、基础语法实践
• GraphQL深入学习：分页、联合类型、关联查询、缓存、数据校验、异常处理等

使用koa2搭建GraphQL服务

NodeJs上实现GraphQL标准的库为graphql，koa2使用koa-graphql发布服务。安装如下依赖：

npm install koa koa-router graphql koa-graphql

如果没有其他路由可以不使用koa-router，用koa-mount将GraphQL挂载到koa应用上即可，见github介绍：https://github.com/chentsulin/koa-graphql

按照惯例，首先写一个hello world程序，如下：

const Koa = require('koa')
const Router = require('koa-router')
const graphqlHTTP = require('koa-graphql')
const { buildSchema } = require('graphql')

const app = new Koa()
const router = new Router()
const schema = buildSchema(`
  type Query {
    hello: String
  }
`)
const root = {
  hello: () => 'Hello world!'
}
router.all('/graphql', graphqlHTTP({
  schema: schema,
  rootValue: root,
  graphiql: true // 开启用于调试的客户端
}))
app.use(router.routes()).use(router.allowedMethods())
app.listen(4000)

schema通过模板字符串来定义比较简洁，再通过rootValue实现对应node的处理方法。还有另一种使用GraphQL的对象来构建，等价于上述写法：

const Koa = require('koa')
const Router = require('koa-router')
const graphqlHTTP = require('koa-graphql')
const { GraphQLSchema, GraphQLString, GraphQLObjectType } = require('graphql')

const app = new Koa()
const router = new Router()

const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'Root',
    fields: {
      hello: {
        type: GraphQLString,
        resolve: () => 'Hello world!'
      }
    }
  })
})
router.all('/graphql', graphqlHTTP({
  schema: schema,
  graphiql: true // 开启用于调试的客户端
}))
app.use(router.routes()).use(router.allowedMethods())
app.listen(4000)

访问http://localhost:4000/graphql?query=%7B%0A%20%20hello%0A%7D可以看到GraphQL服务发布成功了。

Hello world!

GraphQL客户端

GraphQL标准本身是不限定客户端与服务端的协议的，不过最常用的是基于HTTP协议。上文介绍的使用koa搭建的GraphQL服务是基于HTTP协议的，并且所有的请求都通过POST方式发送。因此调用GraphQL服务可以用任何能发起POST请求的工具，如curl、ajax、fetch、postman等，不过由于请求体是需要构造的，对于复杂的GraphQL语句可能写起来不是很方便，下面介绍常用的工具。

GraphiQL

该工具是官方推荐的图形用户页面工具，用于测试GraphQL相当有用，在node中使用graphql搭建的服务，启用GraphiQL方式如下：

graphqlHTTP({
  schema: schema,
  graphiql: true // 开启用于调试的客户端
})

之后访问启动的服务地址，如localhost:4000/graphql，进入如下页面

graphiql界面

右上角有个Docs按钮，可以查看到所有支持的操作和参数，如下：

graphiql docs

此处的截图为后文的CRUD示例的截图

有了这个文档，前端请求服务时就不需要额外的接口文档说明了。

这里以一个简单的查询为例，查看浏览器发送的请求

查询结果

从请求上看，使用POST方式，请求体包含query和variables两部分，因此在用其他工具发送时，只要能构建类似的请求体格式即能发送GraphQL请求。

variables是用于查询语句中的查询条件的变量设置，在同一条语句需要根据不同参数查询多次时非常有用，这里暂不演示。

fetch

GraphiQL主要是用于测试，实际前端开发时主要是使用fetch、axios、ajax等，这里简单介绍使用fetch构造GraphQL请求。

const query = `query {
  users(id: 1000) {
    name
    age
    gender
    labels
  }
}`;
fetch('/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({ query })
})
  .then(r => r.json())
  .then(data => console.log(data));

在控制台运行以上代码，查询的结果与GraphiQL的查询结果是一致的

查询结果

postman

由于GraphiQL是node中的测试工具，对于正式环境或者其他语言实现的GraphQL服务不一定有类似工具，因此可以使用postman来发送GraphQL请求。

首先在header中添加如下头部：

postman发送graphql请求头部

然后可正常编写查询语句，发送请求，如下：

postman发送graphql请求

使用GraphQL实现CRUD

以下示例只修改了示例使用koa2搭建GraphQL服务中实现schema的代码，因此只展示实现schema的代码。

定义GraphQL对象类型，声明其中每一个字段和字段类型。GraphQL中有强类型校验，每个字段都必须明确指定类型，这里使用了其中几种常见的基础类型。

// 性别的枚举值
const Gender = new GraphQLEnumType({
  name: 'Gender',
  values: {
    MALE: { value: 'M' },
    FEMALE: { value: 'F' }
  }
})
// user对象
const User = new GraphQLObjectType({
  name: 'User',
  fields: {
    id: { type: GraphQLInt }, // Int
    name: { type: GraphQLString }, // String
    age: { type: GraphQLInt }, // Int
    gender: { type: Gender }, // 枚举类型
    labels: { type: new GraphQLList(GraphQLString) } // 字符串数据
  }
})

以下实现了条件查询和单条数据查询，对于每个操作，都提供了三个参数：

• type: 返回参数类型
• args: 传入参数类型
• resolve: 该操作对应的执行方法，如果该方法返回的值与声明的返回参数类型不一致会自动报错

const queryObjectType = new GraphQLObjectType({
  name: 'RootQuery',
  fields: {
    users: { // 条件查询
      type: new GraphQLList(User),
      args: {
        id: { type: GraphQLInt },
        name: { type: GraphQLString },
        age: { type: GraphQLInt },
        gender: { type: Gender },
        label: { type: GraphQLString }
      },
      resolve (parent, params) {
        return getUsers(params)
      }
    },
    user: { // 单条数据查询
      type: User,
      args: { id: { type: GraphQLInt } },
      resolve (parent, { id }) {
        return getUserById(id)
      }
    }
  }
})

所有变更的操作(新增、更新、删除)必须放在schema的mutation中，不过实际定义的操作对象与查询的操作对象一样，都包含type、args、resolve，如下实现了新增、更新、删除操作：

const mutationObjectType = new GraphQLObjectType({
  name: 'Mutation',
  fields: {
    addUser: { // 添加用户
      type: User,
      args: {
        name: { type: GraphQLString },
        age: { type: GraphQLInt },
        gender: { type: Gender },
        labels: { type: new GraphQLList(GraphQLString) }
      },
      resolve (parent, params) {
        return addUser(params)
      }
    },
    updateUser: { // 更新用户
      type: User,
      args: {
        id: { type: GraphQLInt },
        name: { type: GraphQLString },
        age: { type: GraphQLInt },
        gender: { type: Gender },
        labels: { type: new GraphQLList(GraphQLString) }
      },
      resolve (parent, params) {
        return updateUser(params)
      }
    },
    removeUser: { // 删除用户
      type: GraphQLBoolean,
      args: {
        id: { type: GraphQLInt }
      },
      resolve (parent, params) {
        return removeUser(params)
      }
    }
  }
})

将上述定义的GraphQL对象添加到schema上：

const schema = new GraphQLSchema({
  query: queryObjectType,
  mutation: mutationObjectType
})

以上的用户数据通过mockjs模拟生成，调用的CRUD方法实现如下：

const Mock = require('mockjs')

let users = Mock.mock({
  'list|5': [{
    'id|+1': 1000,
    'name': /user-[a-zA-Z]{4}/,
    'age|1-100': 100,
    'gender': /(F|M)/,
    'labels': () => ['sportsman', 'programmer', 'teacher', 'musician', 'chef'].filter(() => Math.random() < 0.3)
  }]
}).list

module.exports = {
  getUsers (params) {
    const rules = Object.keys(params).map(one => {
      if (one === 'label') return user => user[one].includes(params[one])
      if (one === 'name') return user => user[one].indexOf(params[one]) > -1
      return user => user[one] === params[one]
    })
    return users.filter(one => rules.every(rule => rule(one)))
  },
  getUserById (id) {
    return users.filter(one => one.id === id)[0]
  },
  addUser (params) {
    const newUser = {
      id: users.reduce((a, b) => a.id > b.id ? a : b).id + 1,
      ...params
    }
    users.push(newUser)
    return newUser
  },
  updateUser (params) {
    let updateUser
    users = users.map(one => {
      if (one.id === params.id) {
        updateUser = {
          ...one,
          ...params
        }
        return updateUser
      }
      return one
    })
    return updateUser
  },
  removeUser (id) {
    users = users.filter(one => one.id !== id)
    return true
  }
}

运行以上代码，打开localhost:4000/graphql，就可以开始体验GraphQL语言的强大了。

查询name中包含'm'的用户，只获取'name'、'gender'字段：

查询结果

查询name中包含'm'的女性用户，获取'name'、'age'、'gender'字段：

查询结果

添加新用户：

添加新用户

更新用户标签：

更新用户标签

删除id为'1003'的用户：

删除用户

总结

在初步使用GraphQL语言后，第一感觉是通过文档可以非常清楚的知道有哪些可以请求的资源，并且可预测返回的数据结构，这一点很有用。因为之前使用rest风格的接口，通常是通过接口文档或其他非强制性的约束返回数据结构，但实际操作后端还是有可能返回异常结构的数据，前端对这种异常是不便处理的。另外客户端灵活定义获取的数据结构也很方便，对于一次查询获取的多种资源，服务端分别调用对应的处理函数，再返回指定字段，组合多种数据返回。参数、响应数据添加了强类型校验，使得请求和响应都是容易预测的。

本文以CRUD为例体验了GraphQL服务的搭建和使用，后续将继续学习分页、关联查询、对象嵌套、缓存、数据校验、异常处理等。

本文参考资源如下：

• http://graphql.cn/graphql-js/
• https://draveness.me/graphql-microservice
• https://jerryzou.com/posts/10-questions-about-graphql/