文章原文请移步我的博客：GraphQL 接口设计
graphql 是一种用于 API 的查询语言。它提供了一套完整的和易于理解的 API 接口数据描述，给客户端权力去精准查询他们需要的数据，而不用再去实现其他更多的代码，使 API 接口开发变得更简单高效。
最近在用Gatsby开发一版静态博客，感觉和这个框架真是相见恨晚。因为这个框架使用到了graphql技术，所以我花了点时间去学习了一下，并且记录了一下学习和思考过程。
本文主要讲解如何理解graphql以及基于关系型数据库设计graphql的思路。如果需要学习graphql基础知识，请移步官方文档
本文包含Nestjs + graphql的示例项目：https://github.com/YES-Lee/nestjs-graphql-starter
理解graphql
graphql是一个用于描述数据及其关系的查询语言，官方文档中描述了graphql的标准，具体的实现依靠第三方，目前主流的是Apollo提供的解决方案。
graphql并不关心具体我们是怎么获取数据的，我们只需要提供获取数据的方法（resolver）以及如何组装数据（schema）。类似于Java开发过程中的接口设计模式，Graphql定义了一套标准，我们按照标准实现接口。下面以用户-角色模型举例。
下面的代码定义了两个数据结构，与JSON类似，应该很容易理解。它描述了每个类型（type）的名称，以及其包含的属性。属性除了可以是基本类型外，也可以是数组、其他引用类型，从而建立起所有数据模型及相互的关系图。
type Role {
name: String
note: String
}
type User {
id: Int
name: String
gender: Int
role: Role
}上面代码用于描述Role和User的数据结构，那么我们具体要怎么使用这个东西呢？先从前端的角度来看，可以从官方文档学习到前端的基本使用，请求体中的数据描述和上面定义类型的代码有些许差别，比如我们要查询用户数据：
query userInfo {
user(id: Int) {
id
name
gender
role {
name
note
}
}
}从上面的代码可以大概猜测出，如果我们不需要查询role数据是，只需要将其从请求中去掉
query userInfo {
user(id: Int) {
id
name
gender
}
}当请求到达服务端时，graphql会对请求体进行解析，当解析到user时，会执行我们定义好的获取user数据的逻辑，解析到role也是同样的道理。那么我们得在服务端定义好获取数据的逻辑，在graphql中叫做resolver。
之前的代码只定义了数据的结构，我们还需要为其创建一个resolver来获取对应的数据，类似于下面的代码
function userResolver (id) {
// ...
// return User
}
function roleResolver (userId) {
// ...
// return Role
}我们可以在resolver中执行sql、http请求、rpc通信等任何能够获取到所需数据的逻辑。最终只需要按照预定义的结构将数据返回即可。
Schema
前面用来定义不同类型数据结构的代码，称做Schema。它是graphql用来描述数据结构和关系的语言，在Schema的type定义中，可以使用Int, Float, String，Boolean, ID等graphql定义的标量类型（Scalar Types），也可以使用联合类型，引用另一个type等，如上面代码User中引用了Role。
Resolver
Resolver是GraphQL中用来获取数据的方法。它不关心Resolver的具体实现，我们可以从数据库, HTTP接口, 服务器资源等渠道获取数据。
graphql会根据请求中声明的字段来执行resolver，一定程度上可以减少查询次数。下面的代码中，会执行UserResolver，结束后再继续执行RoleResolver
{
User {
name
role
}
}如果我们把role字段去掉，那么服务器将不会再执行RoleResolver
{
User {
name
}
}UserResolver执行结束后，就会将数据返回给前端。
可见graphql可以动态的执行数据查询，减少不必要的资源消耗。但是，凡事都有双面性，从另一个角度来思考，我们该如何控制Resolver的粒度？假设我们的Resolver是进行数据库查询，在restful API中，通常我们会使用一个关联查询同时获取到User和Role两个数据。但是在graphql中，我们为每个关联对象都创建一个Resolver，当我们在查询一个用户列表，并且需要包含用户相关的角色时，就会发现一个问题，一次请求需要执行N+1次sql查询：1次UserResolver获取N个用户列表，N次查询获取每个用户的角色。这就是后面需要讲的N+1问题。
graphql存在的问题
N+1问题
N+1问题并不是只存在于graphql中，我们在写sql的时候，也会存在类似的情况，只不过我们会通过关联查询来避免这个问题。
为了解决N+1问题，graphql官方提供了一个dataloader解决方案。dataloader使用了缓存技术，同时也会合并多次相同（类似）的请求，将前面讲到的N次查询合并成一次。基本原理就是先执行查询列表的操作，然后将每条记录的关联字段作为参数列表，通过一次查询拿到所有的关联数据后，再合并到上级数据中。dataloader是目前解决N+1问题比较有效的方法，在使用上也没有太多困难。
其次，我们可以通过控制Resolver的粒度来减少查询次数。比如前面的示例中，不写roleResolver，而是直接通过关联查询，用一次查询获取到User和Role。当然，这样做的话，无论前端是否查询role字段，服务都会进行关联查询，这里需要根据具体场景取舍。
HTTP缓存问题
由于graphql接口请求只有一个统一endpoint，会导致我们无法使用HTTP缓存。目前买一些前端实现中，如Apollo，提供了inMemeryCache解决方案，但在使用上体验不是很友好。
关系型数据库+graphql接口设计
大概了解了graphql之后，我们来开始进行关系型数据库（Mysql）+ graphql的API设计
编写Schema
对于schema的设计，首先忽略表之间的关系，优先建立与数据表对应的模型。如User表和Role表，分别建立如下schema
type User {
name: String
gender: Int
# password: String // 敏感信息不应该出现
}
type Role {
name: String
note: String
}其中需要注意的是，敏感数据不应该出现在敏感信息（用户密码等），即使Resolver的结果包含这些敏感信息，只要schema中没有包含，graphql会自动过滤这些字段。
建立好所有的表对应的schema之后，再来考虑表之间的关系。
表关系的处理
graphql对于关系的处理与Restful API有一些区别，在Restful API中，我们一般只在有需求的接口中建立关系查询，我们会针对接口做一些SQL优化，以求在一条SQL中快速查询出所需要的一切信息。
但是在graphql中，我们应当把所有表的关系描述为一个图结构，保证所有有关系（一对多或多对多）的表对应的schema都是连同的，这样我们在请求的时候，就能够从一个节点到达任意一个与之有关系的节点。
这也是我觉得graphql的一大魅力，当我们建立起完整的关系图后，前端可以自由的查询、组合数据。从理论上来讲，前端可以无限递归查询一组数据，如：小明->小明的朋友->小明的朋友的朋友->...，我们只需要选定好一个起点，便能到达任何地方。
一对多关系
一对多关系的建立很简单，我们只需要编写对应的Resolver，然后在主表对应的schema中添加字段即可
type Role {
name: String
note: String
}
type User {
name: String
gender: Int
role: Role
}function userResolver () {
// ...
// return User
}
function roleResolver (userId) {
// ...
// return Role
}我们写了roleResolver之后，在User中添加了role字段，当请求该字段时，graphql会去执行roleResolver来获取数据，下面来看多对多关系的处理。
多对多关系
通常，在Restful API中，我们会通过一条SQL关联查询，获取多对多的关联数据，但是在graphql中，如果只使用关联查询，显然是没有充分发挥其特性的。我们来看如下示例
# schema
type User {
name: String
gender: Int
role: Role
groups: [Group] # 用户组
userGroups: [UserGroups] # 用户组关系表
}
type Group {
id: Int
name: String
note: String
users: [User]
userGroups: [UserGroups]
}
type UserGroup {
id: Int
userId: Int
groupId: Int
note: String # 关系表中存储一些关联信息
user: User
group: Group
}对于上面的schema，可以看到，在User中包含了groups和userGroups，同样的，在Group中也包含users和userGroups。而在UserGroup中同时包含了User和Group，于是，我们可以进行如下查询
{
user (id: 1) {
name
groups {
id
name
note
userGroups {
id
userId
groupId
note
user {
name
groups {
# ...
}
}
}
}
}
}可能有人会问，上面的操作无限循环了。没错，确实无限循环了，这并不是bug，而是我前面提到的建立起了连同关系。对于不同的场景，我们可以进行不同方式查询，比如当我需要对用户的用户组进行搜索的时候，我可以在groups中添加一些参数
{
user (id: 1) {
name
groups (name: "admin") {
id
name
note
userGroups (userId: 1) {
id
note
}
}
}
}上面的查询，如果我们只想对UserGroup关系表中的额外信息进行搜索时，上面的查询方式可见是行不通的。那么我们可以从另一个方向进行查询
{
user (id: 1) {
name
userGroups (note: "新用户") {
id
userId
groupId
note
group {
id
name
note
}
}
}
}可以发现，通过建立了对应关系的连通图之后，我们可以从一个表查询到任意一个与之关系的表，同时可以无限嵌套查询。
对于无限循环问题无需担心，因为我们需要指定关联字段后，graphql才会去执行对应的Resolver，要想出现死循环，除非我们的查询也无限循环的写下去，显然这是不可能的。
关系处理基本就讲这些内容，如有更好的想法欢迎骚扰。
结束语
本文是我在学习和使用graphql中的实践和思考，如有错误或建议欢迎联系我指正和探讨。另在在实践之前应当着重思考是否需要使用graphql，因为restful api已经能满足大部分的场景需求，盲目的去使用graphql可能会带来一些意料之外的问题。