背景

7月份我们前端团队推动落地了一个 toB 类型的系统,由于服务端也由我们前端工程师来承接,所以服务端技术选型上我们有了话语权,API 这一块儿我们选择了 GraphQL 。本文将阐述我学习 GraphQL 这门技术的一些思考。

GraphQL 在解决什么问题

学习一门新技术,首先要把问题域弄清楚。社区有大量 GraphQL 与传统 API 解决方案(含 REST API)对比文章,总结下来,传统 API 存在以下问题:

  • 接口数量众多维护成本高:接口的数量通常由业务场景的数量决定,为了尽量减少接口数量,服务端工程师通常会对业务做抽象,首先构建粒度较小的数据接口,再根据业务场景对数据接口进行组合,对外暴露业务接口,即便这样,服务端对前端暴露的接口数量还是非常多,因为业务总是多变的。
  • 接口扩展成本高:出于带宽的考虑移动端我们要求接口返回尽量少的字段,PC 端通常要展现更多字段;考虑首屏性能,我们又要求对接口做合并;传统 API 应对这些需求,前后端都面临改造,成本较高。
  • 接口响应的数据格式无法预知:由于接口文档几乎总是不能及时更新,前端工程师无法预知接口响应的数据格式,影响前端开发进度。

针对以上问题,GraphQL 给出了较为完善的解决方案。

GraphQL 如何解决问题

接下来我通过一个实例讲解 GraphQL 解决问题的思路,客户端的述求:根据性别查询团队成员列表,返回 idgendernamenickName ,GrahpQL 的处理过程如下图:

请求参数在发送到服务端之前会先经过 GraphQL Client 转换成客户端 Schema,这段 Schema 其实是一段 query 开头的字符串,描述了客户端的对数据的述求:调用哪个方法,传递什么样的参数,返回哪些字段。服务端拿到这段 Schema 之后,通过事先定义好的服务端 Schema 接收请求参数并执行对应的 resolve 函数提供数据服务。整个过程可以想象成我们吃自助餐的过程,服务端 Schema 就好比自助餐线,摆上我们能提供的所有食物;客户端 Schema 就描述了我们想要吃的食物,按需获取就好了。

讲到这里,好奇心强的同学可能已经开始思考这个问题了:客户端 Schema 本质上就是一段字符串,服务端如何识别并响应这段字符串?

graphql-js

识别与响应客户端 Schema 依赖于官方类库 graphql-js ,服务端拿到客户端 Schema 字符串后会做如下处理:

  • 解析阶段

为了识别客户端 Schema, graphql-js 定义了一系列的特征标识符:

export const TokenKind = Object.freeze({
    BANG: '!',
    DOLLAR: '$',
    PAREN_L: '(',
    PAREN_R: ')',
    SPREAD: '...',
    COLON: ':',
    EQUALS: '=',
    BRACKET_L: '[',
    BRACKET_R: ']',
    ...
});

并定义了 AST 语法树规范,规定语法树支持以下节点:

/**
 * The set of allowed kind values for AST nodes.
 */
export const Kind = Object.freeze({
  // Name
  NAME: 'Name',

  // Document
  DOCUMENT: 'Document',
  OPERATION_DEFINITION: 'OperationDefinition',
  VARIABLE_DEFINITION: 'VariableDefinition',
  VARIABLE: 'Variable',

  // Values
  INT: 'IntValue',
  FLOAT: 'FloatValue',
  STRING: 'StringValue',
  BOOLEAN: 'BooleanValue',
  ...
});

有了特征字符串与 AST 语法树规范,GraphQL Server 对客户端 Schema 进行逐字符扫描(charCodeAt),最终解析阶段的产出物为 document ,上文示例中的客户端 Schema 解析完成之后的部分 document

{
  "kind":"Document",
  "definitions":[
  {
    "kind":"OperationDefinition",
    "operation":"query",
    "name":{
      "kind":"Name",
      "value":"DisplayMember",
      "loc":{
        "start":13,
        "end":26
      }
    },
    "selectionSet":{
      "kind":"SelectionSet",
      "selections":[
        {
          "kind":"Field",
          "alias":null,
          "name":{
            "kind":"Name",
            "value":"fetchByGender",
            "loc":{
              "start":37,
              "end":50
            }
          },
          "arguments":[
            {
              "kind":"Argument",
              "name":{
                "kind":"Name",
                "value":"gender",
                "loc":{
                  "start":51,
                  "end":57
                }
              },
              "value":{
                "kind":"StringValue",
                "value":"M",
                "loc":{
                  "start":59,
                  "end":62
                }
              },
              "loc":{
                "start":51,
                "end":62
              }
            }
          ],
...

如果客户端 Schema 不符合服务端定义的 AST 规范,解析过程会直接抛出语法异常 Syntax Error ,拿上文的示例举例,我将客户端 Schema 中的 fetchByGender(gender: "M") 改为 fetchByGender(gender) ,只传递参数名,不传递参数值,则服务端会响应:

{
    "errors":[
        {
            "message":"Syntax Error GraphQL request (3:29) Expected :, found )

2: query DisplayMember {
3: fetchByGender(gender) {
^
4: list {
",
            "locations":[
                {
                    "line":3,
                    "column":29
                }
            ]
        }
    ]
}

结构化的报错信息也是 GraphQL 的一大特点,定位问题非常方便。只要语法没问题解析阶段就能顺利完成,然后进入校验阶段。

  • 校验阶段

校验阶段用于验证客户端 Schema 是否按照服务端 Schema 定义好的方式获取数据,比如:获取数据的方法名是否有误,必填项是否有值等等,校验范围一共有几十种,我没有办法一一举例。拿上文的示例举例,我将客户端 Schema 中的 fetchByGender 改为 fetchByGenfetchByGen 在服务端根本没有定义,则服务端会响应:

{
    "errors":[
        {
            "message":"Cannot query field "fetchByGen" on type "Query". Did you mean "fetchByGender"?",
            "locations":[
                {
                    "line":3,
                    "column":9
                }
            ]
        }
    ]
}

不仅返回结构化的报错信息,还非常人性化的告诉你正确的调用方式是什么。校验阶段通过之后会进入执行阶段

  • 执行阶段

执行阶段依赖的输入为:解析阶段的产出物 document ,服务端 Schema;其中 document 准确描述了客户端对数据的述求:请求哪个方法,参数是什么,需要哪些字段;服务端 Schema 描述了提供数据的方式;拿上文的示例举例,服务端 Schema 需要这样定义:

const graphqlApi = require('graphql');
const {
  GraphQLObjectType,
  GraphQLList,
  GraphQLNonNull,
  GraphQLSchema,
  GraphQLString,
} = graphqlApi;

const dataSource = require('./dataSource');

const memType = new GraphQLObjectType({
  name: 'Male',
  description: 'A member gender is Male.',
  fields: () => ({
    id: {
      type: new GraphQLNonNull(GraphQLString),
      description: 'The id of member',
    },
    name: {
      type: GraphQLString,
      description: 'The name of the character.',
    },
    nickName: {
      type: GraphQLString,
      description: 'The nickName of the character.',
    },
    gender: {
      type: GraphQLString,
      description: 'The gender of the character.',
    },
    list: {
      type: new GraphQLList(memType),
      description: 'The mems list by gender.',
    },
  })
});

const queryType = new GraphQLObjectType({
  name: 'Query',
  fields: () => ({
    fetchByGender: {
      type: memType,
      args: {
        gender: {
          description: 'gender of the human',
          type: new GraphQLNonNull(GraphQLString),
        },
      },
      resolve: (root, { gender }) => {
        // 访问数据库或三方 API 查询成员列表
        return {
          list: dataSource.getMembers(gender),
        };
      },
    },
  }),
});

module.exports = new GraphQLSchema({
  query: queryType,
  types: [memType],
});

执行服务端 Schema 中的 resolve 函数,得到执行阶段的输出:

{
    "data":{
        "fetchByGender":{
            "list":[
                {
                    "id":"1",
                    "gender":"M",
                    "name":"童开宏",
                    "nickName":"慕冥"
                }
            ]
        }
    }
}

当然要完成服务端 Schema 的定义,你需要学习 GraphQL 的 类型系统 ,大家翻阅 API 文档即可。

技术边界

原理弄清楚之后我们需要对 GraphQL 这门技术的边界有一个清醒的认识:

  • 客户端边界:核心能力是将请求参数按照服务端定义好的 AST 语法树规范拼装成客户端 Schema 字符串,实现方案大家可参考apollo提供的 Webpack 插件 ,当然也有一些 GraphQL 客户端连发送 Ajax 请求的活儿也干了,无非是在底层调用其他类库比如 axios 发请求。
  • 服务端边界:核心能力是识别客户端 Schema 字符串,并通过服务端 Schema 调用底层的数据服务按需返回用户想要的数据,至于底层数据源来自哪里(数据库或者三方接口),以何种方式获取数据(直连数据库或者 ORM 方法调用),这些不属于 GraphQL 关心的范畴。

问题解决的怎么样

由于 GraphQL 通过客户端 Schema 而不是通过 URL 描述数据述求,所以理论上服务端只需要对客户端暴露一个地址即可,解决了接口数量众多维护成本高的问题;同时,服务端提供的是全量字段,客户端可按需获取,面对接口扩展的需求,服务端没有开发成本;最后,通过 GraphiQL 可视化调试界面展现服务端能提供的所有数据,开发过程不再依赖接口文档:

GraphQL 社区在忙什么

GraphQL 官方提供核心能力:

  • graphql-js :GraphQL 理念的 JavaScript 实现,该类库可同时运行在浏览器环境与 Node 环境,该类库的原理我在上文中已经讲过了。
  • graphiql :提升调试体验,我在上文中提过。
  • dataloader :提升性能,通过合并请求尽量减少数据库查询次数。
  • Relay :前端框架,使 GraphQL 与 React 很好的融合在一起,嵌入性较强,需要 GraphQL Server 配合。

我们还缺什么?

  • 服务端

官方只提供了 JavaScript 语言支持,社区爱好者很快在不同编程语言中实现了 GraphQL 的理念:JAVA.NET 等等,更多语言支持,请查看 官网

  • 客户端

官方提供的 Relay 解决了 GraphQL 与 React 相结合的问题,Apollo Client 提供了与其他前端框架融合的解决方案,比如 Vue、Angular 等等。

  • 开发体验

    • graphql-tools :在上文示例代码的服务端 Schema 中,我们将类型的定义(typeDefs)与处理函数的定义(resolvers)放在同一个文件中,职责上不够单一,借助 graphql-tools 我们可以将二者分不同的文件定义;
    • egg-graphql :与 Node 框架 egg 相结合,制定 目录规范 并提供语法糖提高开发效率;

总结

GraphQL 的优点上文已经讲过了,真的是从业务痛点出发,解决了传统 API 存在的问题,但是 GraphQL 在解决问题的同时也带了一些新的问题,这些问题在某种程度上阻碍了这门技术的普及:

  • 数据库性能:GraphQL 将数据描述成一张巨大的网,理论上客户端 Schema 可以写出任意嵌套层级的查询语句,比如:
query IAmEvil {
  author(id: "abc") {
    posts {
      author {
        posts {
          author {
            posts {
              author {
                # that could go on as deep as the client wants!
              }
            }
          }
        }
      }
    }
  }
}

这样的查询语句会给数据库带来很大的性能开销,服务端不得不做 限流 来规避这样的问题,这也带来了额外的开发成本。

  • 侵入性:GraphQL 受益最大的是前端,却需要服务端鼎力支持,特别是老系统迁移,服务端与前端都面临较大的改造。
  • 学习成本:GraphQL 是一套全新的理念,需要前后端同学都学习新的知识才能掌握这门技术,这也带来较大的学习成本。

任何技术都有利弊,大家要结合自己的场景权衡收益做出适合自己的技术选型。

参考文档

03-05 23:46