点击上方“前端小苑”,选择“置顶公众号”
精品技术文章,热门资讯第一时间送达
作者:蔡永敏
项目地址:graphql-basedon-restful[1]
原文:https://zhuanlan.zhihu.com/p/78962152
注:假如觉得二者是互相对立,推荐先看这篇文章:https://callstack.com/blog/the-power-of-graphql-directives/
前不久看了工业聚的文章《GraphQL-BFF:微服务背景下的前后端数据交互方案》[2],非常非常精彩,又重新拾起了对 GraphQL 的兴趣。本身在工作的项目中,已经在使用 GraphQL 了,可能是因为使用方式的原因,觉得用的有点多余,只是有一个 GraphQL 的壳子而已,没有足够发挥出 GraphQL 的优秀特性,使用的方式有所改进但大致和文章中 [5.1] RESTful-Like 模式 描述的方式类似,type 与 type 之间的定义缺乏联系,与 RESTful API 设计对应只是简单的一对一关系,无法发挥出 GraphQL 关联查询的能力。所以那时候对 GraphQL 这一块的知识就没太关注了。
但是 GraphQL 的社区一直都在发展,关于 GraphQL 的 Repo、文章和讨论也越来越多。在去年杭州开了第一届 GraphQLParty,宋小菜前端团队花了很长很长的篇幅[3]介绍了他们在 GraphQL 方面的实践,也非常非常精彩。所以对这一块的知识也还是会有一些关注,期望能找到一个比较理想的使用 GraphQL 的方式。
正好前不久看到了工业聚写的关于 GraphQL 的文章,发现原来是之前的使用方式有问题,才导致认为 GraphQL 带来的成效并不大。看完这篇文章之后,明白了项目在使用方式上的问题,同时也加深了对它的认识。所以决定对 GraphQL 做进一步的了解。所以就有了今天这个项目。这个项目也是从那个时候开始写的,8 月刚开始。
关于 GraphQL 的介绍以及它与 RESTful API 设计的对比已经有很多了,这里就不赘述了。在开始阅读之前,如果对 GraphQL 还不了解的同学,可以先去查阅一些 GraphQL 的基础,比如 GraphQL 的语法介绍[4](中文版[5]),或者查看下面的图片,它把大概要掌握的基础知识都在一张图里面列了出来(来自 graphql-shorthand-notation-cheat-sheet[6])。
如标题所示,这里主要是介绍基于 RESTful API 设计的 GraphQL 服务构建。因为目前项目的接口都是基于 RESTful 规范设计的,这个时候如果想使用 GraphQL,不可能说根据 RESTful 提供的接口用 GraphQL 再实现一遍,这个代价太大了,时间和人力成本各方面都不允许。这个时候如果能直接基于 RESTful API 设计的接口来实现一套 GraphQL 接口是非常好的。RESTful API 接口可以保留且不影响它的后端开发,同时又可以对外提供 GraphQL 的服务,方便前端的使用。
要实现这个功能,其实也不难,使用 GraphQL 的自定义 Directive[7] (指令)就可以完成。自定义指令特性非常实用和便捷,通过编写自定义指令来转换 Schema 的 types、fields 和 arguments,扩展 Schema 字符串所能描述的逻辑。关于自定义指令的介绍,具体可以去看 GraphQL Tools 上关于它的介绍,其中就介绍了怎么样去获取 REST API 的数据( Fetching data from a REST API[8])。
这个项目也就是围绕这个自定义指令展开的,同时也借着这个机会了解 GraphQL 的其他特性。目前这个项目会涉及到的 GraphQL 的特性包括下面的部分,之后随着了解的深入,会继续添加。
•定义 type 来描述各个模块服务•定义 custom scalar type 和 enum type 来扩展 field type•实现自定义指令•query 查询•mutation 操作•query 关联查询•对 query 做 batching 处理•mock 数据•生成 api 文档
在项目实现过程中为了方便考虑,项目中并没有真实实现一个提供 RESTful API 接口的服务,而是用的 json-server[9] 这个 npm 包,模拟了一个 RESTful API 服务。不过毕竟它不是真正的 RESTful API 服务,使用上还是会受到一些限制,比如:
•关联查询的部分,只能查询 /users/:userId/orders
得到一个 orders 数组,不能查 /users/:useId/order
,这样只会得到一个空对象。期望是如果 orders 数组只有一个元素,则返回这个元素对象,也就是 user 与 order 是一对一的关系。这时候需要想办法,所以在 @rest 指令里面加入了 responseAccessor
参数,用于对请求到的数据做处理。•不方便做数据之间的联动,比如我新增了一个定义订单记录,记录了对应的 userId
来表示用户信息,这时候需要联动在对应用户信息记录 orderId
信息表示用户的订单号,来记录它们之间的关联关系。但是目前没有找到方便支持的方法,目前的解决方法是事先设想好关联的数据,手动在创建用户信息那里提前记录设想好的 orderId
数据。
所以会导致 mutation 操作和 field resolver 的时候需要做特殊处理。这个具体会在下面的介绍中讲到,先给大家说明一下。
服务构建过程
构建 GraphQL 服务的过程大致分下面几步:
1.基于 Apollo Server 来创建这个服务2.按照工业聚文章中提到的模块服务设计方式来定义 schema
•定义各种 type•定义 scalar type•定义 enum type•为 schema 添加上 @rest 指令
3.实现 RestDirective 自定义指令。4.模拟一个 REST 服务。5.做 mutation 操作,往服务里存储数据。6.做 query 操作,查询之前存储的数据。7.体验级联查询的效果。8.Batching 和 Caching ?9.Mock 数据。10.API 文档。
1. 基于 Apollo Server 创建 GraphQL 服务
Apollo Server[10] 是一个完全由社区驱动开发的开源工具,使用它能快速便捷地创建出一个 GraphQL 服务。它既能独立提供服务,也能以中间件的形式嵌入到 Nodejs 服务中对外提供服务。它对很多现有的 Nodejs 框架都做了支持,比如我们常用的 Express 和 Koa。这个项目采用的是 Koa 的 apollo-server-koa
中间件来创建服务,并使用 TypeScript 来编写。
下面是主要的实现代码:
import { ApolloServer } from 'apollo-server-koa';
import { GraphQLSchema } from 'graphql';
import { fileLoader, mergeTypes } from 'merge-graphql-schemas';
import { makeExecutableSchema, addMockFunctionsToSchema } from 'graphql-tools';
import { RestDirective } from './directives';
import { dateScalarType } from './scalarTypes';
export function createApolloServer(config: {
// 由于涉及到多个文件下的 Type 定义,这里需要传 schemaDir
// 之后再用 graphql-tools 下的 fileLoader / mergeTypes / makeExecutableSchema 方法
// 得到最终的 schema 定义
schemaDir: string;
// 由于可能会涉及到多个后端服务,这里需要传 endpointMap
// 这在后面的 rest 指令中会用到
endpointMap: { [key: string]: string };
// 服务的 mock 数据配置
mocks: boolean | { [ key: string ]: any };
}) {
const { schemaDir, endpointMap, mocks } = config;
// 准备 schema
const typesArray = fileLoader(schemaDir, { recursive: true });
const typeDefs = mergeTypes(typesArray, { all: true });
const schema: GraphQLSchema = makeExecutableSchema({
typeDefs,
schemaDirectives: {
// 添加 RestDirective 自定义指令
rest: RestDirective,
},
});
// 处理 mock 数据
if (mocks) {
addMockFunctionsToSchema({
schema,
mocks: typeof mocks === 'boolean' ? {} : mocks,
preserveResolvers: true,
});
}
return new ApolloServer({
schema,
context: () => ({
endpointMap
}),
resolvers: {
// 添加 custom scalar type
Date: dateScalarType,
},
});
};
2. 定义 Schema
创建好服务,我们需要定义 Schema 来描述各个服务模块。这里主要采用工业聚在上面文章中提到的方式来设计和定义。
Schema 定义包含以下几部分:
•定义 type 来描述各个模块服务,以及 query 和 mutation 要处理的操作•定义 custom scalar type 和 enum type 来扩展 field type•为 field 添加上 @rest 指令
下面是定义用户服务模块的 userService.gql 文件代码。详情的 Schema 定义,可以去查看 ./examples/koaServer/schema
文件夹下的代码。
directive @rest(
endpoint: String
path: String
method: String
parentAccessorMap: String
responseAccessor: String
) on FIELD_DEFINITION
type User {
id: Int
name: String
}
extend type Order {
user(orderId: Int): User @rest(
endpoint: "endpoint2001"
path: "/orders/:orderId/users"
parentAccessorMap: "{ id: orderId }"
responseAccessor: "[0]"
)
}
extend type Product {
users(productId: Int): [User] @rest(
endpoint: "endpoint2001"
path: "/products/:productId/users"
parentAccessorMap: "{ id: productId }"
)
}
input UserInput {
name: String!
# 提前记录设想好的 orderId 信息
orderId: Int
# 提前记录设想好的 productId 信息
productId: Int
}
extend type Query {
user(userId: Int!): User @rest(
endpoint: "endpoint2001"
path: "/users/:userId"
)
users: [User] @rest(
endpoint: "endpoint2001"
path: "/users"
)
}
extend type Mutation {
createUser(body: UserInput): User @rest(
endpoint: "endpoint2001"
path: "/users"
method: "post"
)
updateUser( userId: Int! body: UserInput ): User @rest(
endpoint: "endpoint2001"
path: "/users/:userId"
method: "patch"
)
}
3. 实现 RestDirective 自定义指令
关于 RestDirective 自定义指令的实现,可以查看 graphql-tools 的文档示例:Fetching data from a REST API[11]。这里说明一下项目中 @rest 指令的主要实现思路。
1.它是定义在 field 上的,用来 resolve field 的值。2.目前提供五个设置参数,分别是:
•endpoint
:接口服务地址的字符串标识,之后根据 context 中 endpointMap 对象的值来获得实际的接口服务地址。•path
:接口请求路径,比如 /api/users/:userId
,这里使用 :userId
的方式来表示需要传递给 path 的 userId 变量。这里与常规的 url route path 定义变量的方式相同,然后用 route-parser[12] 类似功能的 npm 包来解析。•method
:接口请求方法,小写字符,默认为 'get'。•responseAccessor
:对于接口返回的值做处理,它的值实际是 lodash get 方法的第二个参数。•parentAccessorMap
: 在关联查询中,上一级 resolve 的值需要传递一些数据给当前查询,但是参数名有可能不同,比如查用户下的订单数据,需要根据 userId
来查询,但是上一级获取到的用户标识的参数名是 id
,这样参数名就对应不上。这个时候可以通过设置 parentAccessorMap 的值来设置参数名之间的映射关系。parentAccessorMap 值的类型是 String
,但是你可以基本按照正常描述对象的方式来编写,不过目前不支持换行,所以说现在的写法稍微有些不舒服。
•之后会支持写真正的对象,看到过有这种实现的自定义指令,比如 graphql-faker[13] 项目中的 @fake 指令,支持写对象和数组。到时候就不会有这个问题了,不过到时候 @rest 指令的参数格式应该会相应发生改变。•【08/21】更新:详细看了下,发现不行,它其实是一个 input type,并且参数名都是确定的,而 parentAccessorMap 里面的参数名都是不确定的,所以逻辑复用不了。而且还会涉及比较复杂的转换过程,晚上刚更新了一版,估计之后还会有其他情况,逻辑还需要增强。•【08/27】更新:还是用 input type 比较好,可读性也强。不过需要在 @rest directive definition 那里定义 ParentAccessorMapInput
会支持的属性,不然在 parentAccessorMap
中设置的属性会无效(详见示例代码)。
3.实际 field.resolve 函数中要处理的 args 参数对象,项目中会把这个对象里面的参数分成三块:
•一块是 params,附加到 url path 上。•一块是 body,附加到请求体里面。•还有一块是 path args,用于 url route path 的解析。•之后也可以有 headers 参数来自定义一些要发送请求头等等。
4.最后使用 axios 来发送接口请求。5.目前还没有处理接口权限问题。
具体代码可查看 ./src/directives/rest.ts
文件。
4. 模拟 RESTful API 服务
上面提到了,项目中并没有真实实现一个 RESTful API 服务,而是用 json-server 这个 npm 包,模拟了一个。省略了连接数据库,或者连接远程服务的步骤,用本地 json 文件来保存数据对外提供 RESTful API 服务。由于不是主要逻辑模块,实现逻辑这里不详述。下面是实现代码:
import jsonServer from 'json-server';
import path from 'path';
const server = jsonServer.create();
const dbPath = path.join(__dirname, './db.json');
const router = jsonServer.router(dbPath);
const middleware = jsonServer.defaults();
const port = 2001;
server.use(middleware);
server.use(router);
server.use(jsonServer.bodyParser);
server.listen(port, () => {
console.log(`JSON Server is running on: http://127.0.0.1:${port}`);
});
5. 做 mutation 操作,往服务里存储数据
OK,上面算是做好创建服务的基础工作之后,这个时候需要往里面存储数据了。比如说创建用户信息。这里推荐 Altair GraphQL Client[14] 来调试,一个类似于 Postman 的接口调试客户端,挺好用的。
mutation CreateUser($body: UserInput!) {
createUser(body: $body) {
name
}
}
{
"body": {
"name": "gogogo",
"orderId": 1,
"productId": 1
}
}
6. 做 query 操作,查询之前存储的数据
存储了数据之后,就可以对里面的数据进行查询了,比如获取用户信息。
query {
user(userId: 1) {
name
}
}
7. 体验 GraphQL 关联查询
按照上面的步骤分别存储看 users、orders、products 的数据(实际上项目里已经预先存储好了需要调试的数据,可以去 ./examples/jsonServer/db.json
文件下查看),这时候我们一起体验一下 GraphQL 优秀特性之一关联查询。比如查询用户名下的订单数和产品数,每个订单和产品又可以往下查对应的用户信息。一级一级按照各个服务模块之间的关联关系来查询数据。
query userInfo($uid: Int!) {
user(userId: $uid) {
name
orders {
price
user {
name
}
}
collections {
id
description
users {
name
}
}
}
}
{
"uid": 1
}
8. Batching 和 Caching?
这个部分主要涉及到 GraphQL 比较经典的 N+1 问题,它会给服务器带来性能问题。
关于这个问题,facebook 官方关于 graphql 的 github group 下维护了一个叫 dataloder[15] 的包来处理这个问题。主要的操作是 batching 和 caching。详细了解可以去看它的 README 文档。
项目中预计用不了 caching 操作,因为用的是 RESTful API 接口,没有深入到数据库操作那一层,不知道接口数据什么时候会发生变化(如果有办法知道数据什么时候会发生变化也可以用;或者把不可修改数据和其他数据分开,单独对这一部分数据做 caching 操作,一般来说不可修改数据都是比较重要的数据),也就不知道什么时候要更新缓存,保证不了缓存是否新鲜,这样使用过程中肯定会出现问题。batching 操作的话,可以有效去重 event loop 下同一个 tick 内发送的请求,减轻一定的服务端压力。但是面对不同的请求,请求该发还得发,基本避免不了,除非 RESTful 服务有对应的 API 支持。
目前这部分的代码还么有实现,计划本周五(08/23)之前完成。
【08/23】更新:今天实现了一版,用数据测了下,发现有两点想错了:
1.batching 操作并不会去重 event loop 下同一个 tick 内发送的请求,它只是合并成一个请求一起发送了,但其实到最后都是根据一个数组来发送请求的,所以 batching 操作对于 RESTful 服务相当于是无效的。2.caching 操作并不是直接 caching 请求到的数据,而是 caching 发送请求的 Promise,请求还是会发出去,这就意味着可以对 RESTful API 直接做 caching 操作,然后只会发送一次,这很棒!
9. Mock 数据
关于 mock 数据[16],GraphQL 有很自然的优势,因为它本身 field 在定义的时候就确定了数据类型,然后我们再根据它的数据类型来提供 mock 数据。
内置的 scalar type,在打开 mock 数据开关之后,会默认给对应的类型提供 mock 数据(当然也可以修改),对于自定义的 scalar type 和 enum type,我们也可以很轻松地提供 mock 数据,配合上 casual[17] 或者 faker.js[18] 这些模拟数据的工具。
给特定的 field 提供模拟数据,比如说 user 或者 users。就相当于定义了 这个 field 的 resolver,可以拿到传进来的参数,根据传进来的参数动态的返回模拟数据。
上面是需要侵入项目代码的模拟数据的方式,也可以选择在外面另外起一个服务来模拟数据,也可以尝试 graphql-faker[19] 通过扩展现有服务的方式来提供 mock 数据,不改动原有项目代码,它会在项目根目录下创建一个 .grahql
文件。目前在这个库上我还没有太多尝试,所以只是一个尝试建议。
10. 生成 API 文档
同理,GraphQL 也可以很方便地生成 API 文档,而且还可以根据 type 与 type 之间关系,画一张关系图出来。
下面是使用 graphql-voyager[20] 生成的 API 文档,结果如下图:
结语
整个项目实现下来最大的两点感受是:Schema 定义的部分可能需要反复调整,需要对业务模块足够了解,才能比较好的定义出 type 与 type 之间的关联关系;自定义指令方面还需要对参数和参数类型做很好地支持,才能让开发者轻松地使用它来完成他们所需要的功能。
对于如何使用 GraphQL 来说,这个项目只是一个开始,接下来还有很多内容需要去了解和实践,包括对现有实现模块的改进。最后,希望本文对你在 GraphQL 的使用方面有所帮助。
觉得不错欢迎点个 Star,项目地址:graphql-basedon-restful[21]
The End!
参考
•GraphQL-BFF:微服务背景下的前后端数据交互方案[22]•第一届 GraphQLParty 首场工程实践图文版[23]•GraphQL Tools - Schema directives[24]•the-power-of-graphql-directives[25]•GraphQL Tools - Mocking[26]
References
[1]
graphql-basedon-restful: https://github.com/caiyongmin/graphql-basedon-restful[2]
《GraphQL-BFF:微服务背景下的前后端数据交互方案》: https://zhuanlan.zhihu.com/p/75241522[3]
很长很长的篇幅: https://zhuanlan.zhihu.com/p/38283930[4]
GraphQL 的语法介绍: https://graphql.org/learn/[5]
中文版: https://graphql.cn/learn/[6]
graphql-shorthand-notation-cheat-sheet: https://github.com/sogko/graphql-schema-language-cheat-sheet[7]
Directive: https://www.apollographql.com/docs/graphql-tools/schema-directives[8]
Fetching data from a REST API: https://www.apollographql.com/docs/graphql-tools/schema-directives/#fetching-data-from-a-rest-api[9]
json-server: https://github.com/typicode/json-server[10]
Apollo Server: https://github.com/apollographql/apollo-server[11]
Fetching data from a REST API: https://www.apollographql.com/docs/graphql-tools/schema-directives/#fetching-data-from-a-rest-api[12]
route-parser: https://github.com/rcs/route-parser[13]
graphql-faker: https://github.com/APIs-guru/graphql-faker[14]
Altair GraphQL Client: https://altair.sirmuel.design/[15]
dataloder: https://github.com/graphql/dataloader[16]
mock 数据: https://www.apollographql.com/docs/graphql-tools/mocking/[17]
casual: https://github.com/boo1ean/casual[18]
faker.js: https://github.com/Marak/faker.js[19]
graphql-faker: https://github.com/APIs-guru/graphql-faker[20]
graphql-voyager: https://github.com/APIs-guru/graphql-voyager[21]
graphql-basedon-restful: https://github.com/caiyongmin/graphql-basedon-restful[22]
GraphQL-BFF:微服务背景下的前后端数据交互方案: https://zhuanlan.zhihu.com/p/75241522[23]
第一届 GraphQLParty 首场工程实践图文版: https://zhuanlan.zhihu.com/p/38283930[24]
GraphQL Tools - Schema directives: https://www.apollographql.com/docs/graphql-tools/schema-directives/[25]
the-power-of-graphql-directives: https://callstack.com/blog/the-power-of-graphql-directives/[26]
GraphQL Tools - Mocking: https://www.apollographql.com/docs/graphql-tools/mocking/