GraphQL 速记手册

[coconilu]

概述

GraphQL 是由 Facebook 开发的，用于解决他们巨大、老旧的架构的数据请求问题。

主要组成部分如下：

类型系统（Type System）
查询语言（Query Language）
执行语义（Execution Semantics）
静态验证（Static Validation）
类型检查（Type Introspection）

GraphQL 使用 Schema 来描述数据，并通过制定和实现 GraphQL 规范定义了支持 Schema 查询的 DSQL （Domain Specific Query Language，领域特定查询语言）。

Schema 帮助将复杂的业务模型数据抽象拆分成细粒度的基础数据结构。
DSQL 的实现则赋予了前端开发者自由组织和定制请求数据的能力。

运作过程

对于服务端

首先需要服务端定义可获取对象数据——schema，然后通过业务逻辑返回数据。

对于客户端

客户端通过特定的查询语言去服务器获取数据。

仅需要提供想要获取的对象和它的字段，还要筛选对象的属性值。

与Restful的联系

过程和Restful很相似。
但是GraphQL的目标是获取的资源是可以自定义的，比方说，如果为了获取用户的信息，Restful返回了用户的所有可获取信息；但是GraphQL允许客户端仅获取其中的一部分。

客户端

核心概念

1. 字段（Fields），请求返回的内容
2. 参数（Arguments），用于查询数据
3. 别名（Aliases），解决返回字段冲突
4. 片段（Fragments），可复用单元
5. 操作名称（Operation Name），鼓励使用
6. 变量（Variables），用动态值代替静态值
7. 指令（Directives），核心规范包含@include(if: Boolean)、@Skip(if: Boolean)
8. 变更（Mutations），更新操作
9. 内联片段（Inline Fragments）

查询语言

一个普通的案例，包含字段、参数、别名、操作名称、变量、指令：

query operation_name($episode: Episode = "JEDI", $withFriends: Boolean!){
  empireHero: hero(episode: EMPIRE) {
    name
    friends @include(if: $withFriends) {
      name
    }
  }
  jediHero: hero(episode: JEDI) {
    name
    friends @include(if: $withFriends) {
      name
    }
  }
}

query，指操作类型
operation_name，指操作名称
$episode和$withFriends，指变量
Episode和Boolean，指变量类型
"JEDI"，指变量的默认值
empireHero和jediHero，指别名
hero、name、friends，指字段
episode，指参数
EMPIRE和JEDI，指参数值
@include，指的是指令

可以简单地把GraphQL的查询语言(Queries)当成是没有值只有属性的对象

服务端

类型系统

标量（scalar）

Int：有符号 32 位整数。
Float：有符号双精度浮点值。
String：UTF‐8 字符序列。
Boolean：true 或者 false。
ID：ID 标量类型表示一个唯一标识符，通常用以重新获取对象或者作为缓存中的键。ID 类型使用和 String 一样的方式序列化；然而将其定义为 ID 意味着并不需要人类可读型。

所有的GraphQL操作必须指明到最底层的field，并且返回值为标量，以确保响应结果的结构明白无误

对象类型

一个 GraphQL schema 中的最基本的组件是对象类型，它就表示你可以从服务上获取到什么类型的对象，以及这个对象有什么字段。

相关类型

1. 枚举类型（Enumeration Types）
2. 列表（Lists）
3. 非空（Non-Null）
4. 接口（Interfaces），一个接口是一个抽象类型，它包含某些字段，而对象类型必须包含这些字段，才能算实现了这个接口
5. 联合类型（Union Types），联合类型的成员需要是具体对象类型
6. 输入类型（Input Types），在变更（mutation）中特别有用，因为有时候你需要传递一整个对象作为新建对象

简单的示例

基于graphql-js库的示例：

var { graphql, buildSchema } = require('graphql');

var schema = buildSchema(`
  schema {
    query: Query
  }
  type Query {
    person(age: Int): Person
  }
  type Person {
    name: String
    age: Int
  }
`);

var root = {
  person: (params) => ({ name: 'alpha', age: params.age })
};

graphql(schema, 'query test_query{ person(age: 27){name, age} }', root).then((response) => {
  console.log(response);
});

// 输出
{ data: { person: { name: 'alpha', age: 27 } } }

开源项目

目前很看好Apollo-server

参考

GraphQL官方文档
深入理解 GraphQL
[译] 我经常听到的 GraphQL 到底是什么？