GraphQL 一种用于 API 的查询语言

官方文档：https://graphql.cn/
参考文章：GraphQL 入门看这篇就够了

什么是GraphQL

一种用于 API 的查询语言。

背景

传统的 API 拿到的是前后端约定好的数据格式。

前端的开发随着 SPA 框架全面普及，组件化开发也随之成为大势所趋，各个组件分别管理着各自的状态，组件化给前端仔带来便利的同时也带来了一些烦恼。比如，组件需要负责把异步请求的状态分发给子组件或通知给父组件，这个过程中，由组件间通信带来的结构复杂度、来源不明的数据源、不知从何订阅的数据响应会使得数据流变得杂乱无章，也使得代码可读性变差，以及可维护性的降低，为以后项目的迭代带来极大困难。

试想一下你都开发完了，产品告诉你要大改一番，从接口到组件结构都得改，后端也骂骂咧咧不愿配合让你从好几个 API 里取数据自己组合，这酸爽！

在一些产品链复杂的场景，后端需要提供对应 WebApp、WebPC、APP、小程序、快应用等各端 API，此时 API 的粒度大小就显得格外重要，粗粒度会导致移动端不必要的流量损耗，细粒度则会造成函数爆炸 (Function Explosion)；在此情景下 Facebook 的工程师于 2015 年开源了 GraphQL 规范，让前端自己描述自己希望的数据形式，服务端则返回前端所描述的数据结构。

比如前端希望返回一个 ID 为 233 的用户的名称和性别，并查找这个用户的前十个雇员的名字和 Email，再找到这个人父亲的电话，和这个父亲的狗的名字（别问我为什么有这么奇怪的查找），那么我们可以通过 GraphQL 的一次 query 拿到全部信息，无需从好几个异步 API 里面来回找：

query {
  user (id : "233") {
    name
    gender
    employee (first: 10) {
      name
      email
    }
    father {
      telephone
      dog {
          name
      }
    }
  }
}

返回的数据格式则刚好是前端提供的数据格式，不多不少，是不是心动了？

目前前后端的结构大概如下图。

后端通过 DAO 层与数据库连接实现数据持久化，服务于处理业务逻辑的 Service 层，Controller 层接受 API 请求调用 Service 层处理并返回；前端通过浏览器 URL 进行路由命中获取目标视图状态，而页面视图是由组件嵌套组成，每个组件维护着各自的组件级状态，一些稍微复杂的应用还会使用集中式状态管理的工具，比如 Vuex、Redux、Mobx 等。前后端只通过 API 来交流，这也是现在前后端分离开发的基础。

如果使用 GraphQL，那么后端将不再产出 API，而是将 Controller 层维护为 Resolver，和前端约定一套 Schema，这个 Schema 将用来生成接口文档，前端直接通过 Schema 或生成的接口文档来进行自己期望的请求。

经过几年一线开发者的填坑，已经有一些不错的工具链可以使用于开发与生产，很多语言也提供了对 GraphQL 的支持，比如 JavaScript/Nodejs、Java、PHP、Ruby、Python、Go、C# 等。

一些比较有名的公司比如 Twitter、IBM、Coursera、Airbnb、Facebook、Github、携程等，内部或外部 API 从 RESTful 转为了 GraphQL 风格，特别是 Github，它的 v4 版外部 API 只使用 GraphQL。据一位在 Twitter 工作的大佬说硅谷不少一线二线的公司都在想办法转到 GraphQL 上，但是同时也说了 GraphQL 还需要时间发展，因为将它使用到生产环境需要前后端大量的重构，这无疑需要高层的推动和决心。

正如尤雨溪所说，为什么 GraphQL 两三年前没有广泛使用起来呢，可能有下面两个原因：

1. GraphQL 的 field resolve 如果按照 naive 的方式来写，每一个 field 都对数据库直接跑一个 query，会产生大量冗余 query，虽然网络层面的请求数被优化了，但数据库查询可能会成为性能瓶颈，这里面有很大的优化空间，但并不是那么容易做。FB 本身没有这个问题，因为他们内部数据库这一层也是抽象掉的，写 GraphQL 接口的人不需要顾虑 query 优化的问题。
2. GraphQL 的利好主要是在于前端的开发效率，但落地却需要服务端的全力配合。如果是小公司或者整个公司都是全栈，那可能可以做，但在很多前后端分工比较明确的团队里，要推动 GraphQL 还是会遇到各种协作上的阻力。

大约可以概括为性能瓶颈和团队分工的原因，希望随着社区的发展，基础设施的完善，会渐渐有完善的解决方案提出，让广大前后端开发者们可以早日用上此利器。

特点

请求你所要的数据 不多不少

向你的 API 发出一个 GraphQL 请求就能准确获得你想要的数据，不多不少。 GraphQL 查询总是返回可预测的结果。使用 GraphQL 的应用可以工作得又快又稳，因为控制数据的是应用，而不是服务器。

获取多个资源 只用一个请求

GraphQL 查询不仅能够获得资源的属性，还能沿着资源间引用进一步查询。典型的 REST API 请求多个资源时得载入多个 URL，而 GraphQL 可以通过一次请求就获取你应用所需的所有数据。这样一来，即使是比较慢的移动网络连接下，使用 GraphQL 的应用也能表现得足够迅速。

描述所有的可能（类型系统）

GraphQL API 基于类型和字段的方式进行组织，而非入口端点。你可以通过一个单一入口端点得到你所有的数据能力。GraphQL 使用类型来保证应用只请求可能的数据，还提供了清晰的辅助性错误信息。应用可以使用类型，而避免编写手动解析代码。

API 演进 无需划分版本

给你的 GraphQL API 添加字段和类型而无需影响现有查询。老旧的字段可以废弃，从工具中隐藏。通过使用单一演进版本，GraphQL API 使得应用始终能够使用新的特性，并鼓励使用更加简洁、更好维护的服务端代码。

使用你现有的数据和代码

GraphQL 让你的整个应用共享一套 API，而不用被限制于特定存储引擎。GraphQL 引擎已经有多种语言实现，通过 GraphQL API 能够更好利用你的现有数据和代码。你只需要为类型系统的字段编写函数，GraphQL 就能通过优化并发的方式来调用它们。

重要概念

这里先介绍几个对理解 GraphQL 比较重要的概念，其他类似于指令、联合类型、内联片段等更复杂的用法，参考 GraphQL 官网文档 ~

操作类型 Operation Type

GraphQL 的操作类型可以是 query、mutation 或 subscription，描述客户端希望进行什么样的操作

1. query 查询：获取数据，比如查找，CRUD 中的 R
2. mutation 变更：对数据进行变更，比如增加、删除、修改，CRUD 中的 CUD
3. substription 订阅：当数据发生更改，进行消息推送

对象类型和标量类型 Object Type & Scalar Type

如果一个 GraphQL 服务接受到了一个 query，那么这个 query 将从 Root Query 开始查找，找到对象类型（Object Type）时则使用它的解析函数 Resolver 来获取内容，如果返回的是对象类型则继续使用解析函数获取内容，如果返回的是标量类型（Scalar Type）则结束获取，直到找到最后一个标量类型。

1. 对象类型：用户在 schema 中定义的 type
2. 标量类型：GraphQL 中内置有一些标量类型 String、Int、Float、Boolean、ID，用户也可以定义自己的标量类型

比如在 Schema 中声明：

type User {
  name: String!
  age: Int
}

这个 User 对象类型有两个字段，name 字段是一个为 String 的非空标量，age 字段为一个 Int 的可空标量。

模式 Schema

如果你用过 MongoOSE，那你应该对 Schema 这个概念很熟悉，翻译过来是『模式』。

它定义了字段的类型、数据的结构，描述了接口数据请求的规则，当我们进行一些错误的查询的时候 GraphQL 引擎会负责告诉我们哪里有问题，和详细的错误信息，对开发调试十分友好。

Schema 使用一个简单的强类型模式语法，称为模式描述语言（Schema Definition Language, SDL），我们可以用一个真实的例子来展示一下一个真实的 Schema 文件是怎么用 SDL 编写的：

# src/schema.graphql

# Query 入口
type Query {
    hello: String
    users: [User]!
    user(id: String): [User]!
}

# Mutation 入口
type Mutation {
    createUser(id: ID!, name: String!, email: String!, age: Int,gender: Gender): User!
    updateUser(id: ID!, name: String, email: String, age: Int, gender: Gender): User!
    deleteUser(id: ID!): User
}

# Subscription 入口
type Subscription {
    subsUser(id: ID!): User
}

type User implements UserInterface {
    id: ID!
    name: String!
    age: Int
    gender: Gender
    email: String!
}

# 枚举类型
enum Gender {
    MAN
    WOMAN
}

# 接口类型
interface UserInterface {
    id: ID!
    name: String!
    age: Int
    gender: Gender
}

这个简单的 Schema 文件从 Query、Mutation、Subscription 入口开始定义了各个对象类型或标量类型，这些字段的类型也可能是其他的对象类型或标量类型，组成一个树形的结构，而用户在向服务端发送请求的时候，沿着这个树选择一个或多个分支就可以获取多组信息。

注意：在 Query 查询字段时，是并行执行的，而在 Mutation 变更的时候，是线性执行，一个接着一个，防止同时变更带来的竞态问题，比如说我们在一个请求中发送了两个 Mutation，那么前一个将始终在后一个之前执行。

解析函数 Resolver

前端请求信息到达后端之后，需要由解析函数 Resolver 来提供数据，比如这样一个 Query：

query {
  hello
}

那么同名的解析函数应该是这样的

Query: {
  hello (parent, args, context, info) {
    return ...
  }
}

解析函数接受四个参数，分别为

1. parent：当前上一个解析函数的返回值
2. args：查询中传入的参数
3. context：提供给所有解析器的上下文信息
4. info：一个保存与当前查询相关的字段特定信息以及 schema 详细信息的值

解析函数的返回值可以是一个具体的值，也可以是 Promise 或 Promise 数组。

一些常用的解决方案如 Apollo 可以帮省略一些简单的解析函数，比如一个字段没有提供对应的解析函数时，会从上层返回对象中读取和返回与这个字段同名的属性。

请求格式

GraphQL 最常见的是通过 HTTP 来发送请求，那么如何通过 HTTP 来进行 GraphQL 通信呢

举个栗子，如何通过 Get/Post 方式来执行下面的 GraphQL 查询呢

query {
  me {
    name
  }
}

Get 是将请求内容放在 URL 中，Post 是在 content-type: application/json 情况下，将 JSON 格式的内容放在请求体里

# Get 方式
http://myapi/graphql?query={me{name}}

# Post 方式的请求体
{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}

返回的格式一般也是 JSON 体

# 正确返回
{
  "data": { ... }
}

# 执行时发生错误
{
  "errors": [ ... ]
}

如果执行时发生错误，则 errors 数组里有详细的错误信息，比如错误信息、错误位置、抛错现场的调用堆栈等信息，方便进行定位。