GraphQL学习之原理篇

时间  2019-12-01
标签 graphql 学习 原理 繁體版
原文   原文链接

前言

在上一篇文章基础篇中，咱们介绍了GraphQL的语法以及类型系统，算是对GraphQL有个基本的认识。在这一篇中，咱们将会介绍GraphQL的实现原理。说到原理，咱们就不得不依托于GraphQL的规范：GraphQLgit

概述

GraphQL规范主体部分有6大部分，除去咱们在上一节讲到的类型系统(Type System)和语言(Language)，剩下的即是整个GraphQL的主流程。也就是以下图所示的：github

根据规范的章节，也就是GraphQL的实现流程，咱们原理篇一一来看看规范到底定义了些什么，以及在实际的使用中，是如何贴近到规范的实现的。express

Js语言的实现版本是： graphql-js数组

流程总览

首先咱们确定会在客户端上书写查询语句，查询语句在发送到服务端以前会转换为标准的请求体。以以前的demo为例子，当咱们发起以下的请求的时候：bash

客户端发起的请求体应该具有如下三个字段(POST请求)：服务器

{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}
复制代码

截图以下：函数

参考Serving over HTTP学习

这些参数表达了客户端的诉求：调用哪一个方法，传递什么样的参数，返回哪些字段。ui

服务端拿到这段Schema以后，经过事先定义好的服务端Schema接收请求参数，校验参数，而后执行对应的resolver函数，执行完成返回数据。spa

在express-graphql这个包咱们能够看到服务端的总体处理流程，缩略以下：

...
function graphqlHTTP(options: Options): Middleware {
  ...
  // 返回express的中间件形式的函数
  return function graphqlMiddleware(request: $Request, response: $Response) {
    ...
    // 处理request的参数,解析出来
    return getGraphQLParams(request)
    .then(
      graphQLParams => {}, // 解析成功
      error => {} // 解析失败
    )
    .then(
      optionsData => {
        ...

        // GraphQL只支持GET/POST方法
        if (request.method !== 'GET' && request.method !== 'POST') {
          response.setHeader('Allow', 'GET, POST');
          throw httpError(405, 'GraphQL only supports GET and POST requests.');
        }

        ...

        // 校验服务端这边定义的Schema
        const schemaValidationErrors = validateSchema(schema);

        ...

        // 根据query生成GraphQL的Source
        const source = new Source(query, 'GraphQL request');

        // 根据Source生成AST
        try {
          documentAST = parseFn(source);
        } catch (syntaxError) {
          // Return 400: Bad Request if any syntax errors errors exist.
          response.statusCode = 400;
          return { errors: [syntaxError] };
        }

        // 校验AST
        const validationErrors = validateFn(schema, documentAST, [
          ...specifiedRules,
          ...validationRules,
        ]);

        ...

        // 检查GET请求方法是否在Query操做符上
        if (request.method === 'GET') {...}

        // 执行resolver函数

      }
    )
    .then(result => {
      ... // 处理GraphQL返回的响应体，作些额外的工做。
    })
  }
}
复制代码

更多细节请查看源码。

自省(Introspection)

GraphQL服务器支持根据本身的schema进行自省。这对于咱们想要查询一些关心的信息颇有用。好比咱们能够查询demo的一些关心的类型：

根据规范，有两类自省系统：类型名称自省(__typename)和schema自省(__schema和__type)。

__typename

GraphQL支持在一个查询中任何一个节点添加对类型名称的自省，在识别Interface/Union类型实际使用的类型的时候比较经常使用，在上图演示，咱们能够看到每一个节点均可以添加__typename，返回的类型也有不少：__Type、__Field、__InputValue、__Schema

带有__的都是GraphQL规范内部定义的类型，属于保留名称。开发者自定义的类型不容许出现__字符，不然在语法校验的时候会失败。

举个例子：

将demo中的type Message改成type __Message，而后会报此类错误：

Name \"__Message\" must not begin with \"__\", which is reserved by GraphQL introspection.

__schema&__type

__schema能够用来查询系统当前支持的全部语法，包括query语法、mutation语法，看它的结构就知道了：

type __Schema {
  types: [__Type!]! => 查询系统当前定义的全部类型，包括自定义的和内部定义的全部类型
  queryType: __Type!  => 查询 type Query {} 里面全部的查询方法
  mutationType: __Type => 查询 type Mutation {} 里面全部的mutation方法
  subscriptionType: __Type => 查询 type Subscription {} 里面全部subscription方法
  directives: [__Directive!]! => 查询系统支持的指令
}
复制代码

而__type则是用来查询指定的类型属性。关于这些类型的内部定义请参考：Schema Introspection

上图基于的Message类型是这样的：

"""消息列表"""
type Message {
  """文章ID"""
  id: ID!
  """文章内容"""
  content: String
  """做者"""
  author: String
  """废弃的字段"""
  oldField: String @deprecated(reason: "Use \`newField\`.")
}
复制代码

Tips: 由于有了自省系统，GraphiQL才有可能在你输入查询信息地时候进行文字提示，由于在页面加载的时候GraphiQL会去请求这些内容，请求的内容能够看这个文件：introspectionQueries.js

校验

在上面的流程总览中提到，客户端发起的请求query字段带有查询的语法，这段语法要先通过校验，咱们如下面最简单的一次查询为例：

{
  getMessage {
    content
    author
  }
}
复制代码

解析出来的请求参数数据是：

{ query: '{\n getMessage {\n content\n author\n }\n}',
  variables: null,
  operationName: null,
  raw: false
}
复制代码

以后先是校验服务端定义的schema:validateSchema(schema)，上一节的那个错误就是在这边抛出的。

接着将客户端的query转为Source类型的结构：

{
  body: '{\n getMessage {\n content\n author\n }\n}',
  name: 'GraphQL request',
  locationOffset: { line: 1, column: 1 }
}
复制代码

接着转为AST：graphql.parse，graphql-js根据特征字符串：

export const TokenKind = Object.freeze({
  SOF: '<SOF>',
  EOF: '<EOF>',
  BANG: '!',
  DOLLAR: '$',
  AMP: '&',
  PAREN_L: '(',
  PAREN_R: ')',
  SPREAD: '...',
  COLON: ':',
  EQUALS: '=',
  AT: '@',
  BRACKET_L: '[',
  BRACKET_R: ']',
  BRACE_L: '{',
  PIPE: '|',
  BRACE_R: '}',
  NAME: 'Name',
  INT: 'Int',
  FLOAT: 'Float',
  STRING: 'String',
  BLOCK_STRING: 'BlockString',
  COMMENT: 'Comment',
});
复制代码

对source逐一解析生成lexer，再执行parseDocument生成解析阶段的产出物document：

{
  "kind": "Document",
  "definitions": [{
    "kind": "OperationDefinition",
    "operation": "query",
    "variableDefinitions": [],
    "directives": [],
    "selectionSet": {
      "kind": "SelectionSet",
      "selections": [{
        "kind": "Field",
        "name": {
          "kind": "Name",
          "value": "getMessage",
          "loc": {
            "start": 4,
            "end": 14
          }
        },
        "arguments": [],
        "directives": [],
        "selectionSet": {
          "kind": "SelectionSet",
          "selections": [{
              "kind": "Field",
              "name": {
                "kind": "Name",
                "value": "content",
                "loc": {
                  "start": 21,
                  "end": 28
                }
              },
              "arguments": [],
              "directives": [],
              "loc": {
                "start": 21,
                "end": 28
              }
            },
            {
              "kind": "Field",
              "name": {
                "kind": "Name",
                "value": "author",
                "loc": {
                  "start": 33,
                  "end": 39
                }
              },
              "arguments": [],
              "directives": [],
              "loc": {
                "start": 33,
                "end": 39
              }
            }
          ],
          "loc": {
            "start": 15,
            "end": 43
          }
        },
        "loc": {
          "start": 4,
          "end": 43
        }
      }],
      "loc": {
        "start": 0,
        "end": 45
      }
    },
    "loc": {
      "start": 0,
      "end": 45
    }
  }],
  "loc": {
    "start": 0,
    "end": 45
  }
}
复制代码

其中AST支持的kind能够参考这里的定义: kinds.js

若是同时有多段语法，好比：

query gm($id: ID) {
  all: getMessage  {
    content
    author
  }
  single: getMessage(id: $id) {
    content
    author
  }
}
mutation cr($input: MessageInput) {
  createMessage(input: $input) {
    id
  }
}
复制代码

那么生成的documentAST就是：

[ { kind: 'OperationDefinition',
    operation: 'query',
    name: { kind: 'Name', value: 'gm', loc: [Object] },
    variableDefinitions: [ [Object] ],
    directives: [],
    selectionSet: { kind: 'SelectionSet', selections: [Array], loc: [Object] },
    loc: { start: 0, end: 128 } },
  { kind: 'OperationDefinition',
    operation: 'mutation',
    name: { kind: 'Name', value: 'cr', loc: [Object] },
    variableDefinitions: [ [Object] ],
    directives: [],
    selectionSet: { kind: 'SelectionSet', selections: [Array], loc: [Object] },
    loc: { start: 129, end: 210 } } ]
复制代码

这种状况下，必须提供一个operationName来肯定操做的是哪一个document!该字段也就是咱们在最开始说的请求的数据中的operationName，这些校验都发声在源码的buildExecutionContext方法内

接着执行校验的最后一个步骤：校验客户端语法并给出合理的解释, graphql.validate(schema, documentAST, validationRules)，好比我在将query语句变动为：

{
  getMessage1 {
    content
    author
  }
}
复制代码

graphql-js就会校验不经过，而且给出对应的提示：

{
  "errors": [
    {
      "message": "Cannot query field \"getMessage1\" on type \"Query\". Did you mean \"getMessage\"?",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ]
    }
  ]
}
复制代码

这种结构化的报错信息也是GraphQL的一大特色，定位问题很是方便。只要语法没问题校验阶段就能顺利完成。

执行阶段

graphql.execute是实现GraphQL规范的Execute章节的内容。根据规范，咱们将执行阶段分为：

每一个阶段解释一下：

  1. Validating Requests：到这个阶段的校验其实已经不多了，在源码实现上只须要校验入参是否符合规范便可，对应源码的方法是：assertValidExecutionArguments
  2. Coercing Variable Values：检查客户端请求变量的合法性，须要和schema进行比对，对应源码的方法是：getVariableValues
  3. Executing Operations：执行客户端请求的方法与之对应的resolver函数。对应源码的方法是：executeOperation
  4. Executing Selection Sets：搜罗客户端请求须要返回的字段集合，对应源码的方法是：collectFields
  5. Executing Fields：执行每一个字段，须要进行递归，对应源码的方法是：executeFields

接下去咱们大概讲解下每一个过程的一些要点

Validating Requests

源码中校验了入参的三个：schema/document/variables

Coercing Variable Values

若是该操做定义了入参，那么这些变量的值须要强制与方法声明的入参类型进行比对。比对不经过，直接报错，好比咱们将getMessage改成这样：

query getMessage($id: ID){
  getMessage(id: $id) {
    content
    author
  }
}
复制代码

而后变量是：

{
  "id": []
}
复制代码

那么通过这个函数将会报错返回："Variable \"$id\" got invalid value []; Expected type ID; ID cannot represent value: []"

Executing Operations => Executing Selection Sets => Executing Fields

在该流程上区分operation是query仍是mutation，两者执行的方式前者是并行后者是串行。

总体流程以下所示：

在图中标注的输出的第一次执行的数据以下，仅供参考，流程图以demo中的getMessage为例子所画，其中粉红色是第一次波执行的流程，也就是解析getMessage这个字段所走的流程，以completeValueCatchingError为界限是开始遍历[Message]中的Message，这个流程以紫色线标注，如此往复递归，遍历完客户端要求的全部数据为止

  1. collectFields
{ getMessage:
  [{
    kind: 'Field',
    alias: undefined,
    name: [Object],
    arguments: [],
    directives: [],
    selectionSet: [Object],
    loc: [Object]
  }]
}
复制代码
  1. resolveFieldValueOrError 其入参第一次传进去的source是：
{
  getMessage: [Function: getMessage],
  createMessage: [Function: createMessage],
  updateMessage: [Function: updateMessage]
}
复制代码

第一次执行返回的结果：

[
  { id: 0, content: 'test content', author: 'pp' },
  { id: 1, content: 'test content 1', author: 'pp1' }
]
复制代码
  1. completeValueCatchingError
[
  { content: 'test content', author: 'pp' },
  { content: 'test content 1', author: 'pp1' }
]
复制代码

整个流程以getMessage这个字段名称为起点，执行resolver函数，获得结果，由于返回类型是[Message]，因此会对该返回类型先进行数组解析，再解析数组里面的字段，以此不断重复递归，直到获取完客户端指定的全部字段。图形化的流程我在图中用标号和颜色标注，应该很容易看懂整个流程的。

执行resolver函数的选择

在这里回答demo中提到的问题，一种写法是将schema和resolve分别传入schema和rootValue两个字段内，另一种写法是使用graphql-tools将typedefs和resolvers转换成带有resolve字段的schema,两者写法都是可行的，缘由以下：

首先代码会给系统默认的fieldResolver赋值一个defaultFieldResolver函数，若是fieldResolver没有传值的话，这里明显没有传值。

以后在选择resolver函数执行的时候有这么一段代码来实现了上述两种写法的可行性(resolveField.js)：

const resolveFn = fieldDef.resolve || exeContext.fieldResolver;
复制代码

这样就优先使用schema定义的resolve函数，没有的话就使用了rootValue传递的resolver函数了。所以执行的不同的话致使resolver函数获取参数的方式略微不一样：

第一种入参是：(args, contextValue, info) 第二种入参是：(source, args, contextValue, info) => 也就是此时你想要获取参数的话得从第二个字段开始

Response

Response步骤就很简单了，定义了4个规则：

一、响应体必须是一个对象

二、若是执行operation错误的时候，那么errors必须存在，不然不该该有这个字段

2.1. `error`字段是一个数组对象，对象里面必须包含一个`message`的字段来描述错误的缘由以及一些提示

2.2. 另外可能包含的字段有`location`、`path`、`extensions`来提示开发者错误的具体信息。
复制代码

三、若是执行operation没有错误，那么data字段必须有值

四、其余自定义的信息能够定义在extensions这个字段内。

最后

至此，整个GraphQL实现的流程到这里就结束了。更多细节请查看源码和规范，咱们将在下一篇文章中聊聊GraphQL的实际项目应用GraphQL学习之实践篇

参考

一、 GraphQL

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程