分分钟将REST转换为GraphQL

这个指南教你在不修改任何代码的情况下,完成从REST到GraphQL的迁移。这样,GraphQL就能让你的REST真正休息一下了!

从REST到GraphQL

GraphQL的支持者在宣传推广GraphQL方面已经做得非常好了。出于对他们努力的尊重,我就不再深入介绍细节,只是稍微总结一下:

  1. GraphQL允许我们在单个请求中获取多个资源;
  2. 通过精确描述所需数据,GraphQL解决了REST过度抓取数据的问题;
  3. GraphQL借助在一个请求中获取相关的数据,解决了前端N+1查询的问题。

本指南中,我会介绍大多数倡导GraphQL的人所忽略的一个点,就是“我们在REST上有了巨大投入”。这意味着:

  • 我们大多数的服务都是基于REST的;
  • 我们更愿意编写REST服务;
  • 我们希望支持使用REST API的现有客户端。

虽然有许多文章帮我们从REST迁移到GraphQL,但这些做法都迫使我们更改现有的代码库或在REST服务前面编写新的代码库。

但是,稍等一下……

如果它还能运行,就别去碰它。

这难道不是编程的第一规则吗?

迁移可能非常痛苦,尤其是面对巨大的代码库时,更会令人望而生畏。随时存在将已有功能破坏掉的可能性。

我们为什么不能继续保持REST呢?我们天性懒惰,都喜欢用简单的技巧和容易的解决方案。

如果有一种方式,让我们原样保持REST服务,且无需任何代码变更就能在其之上实现一个GraphQL层,那会怎样?听起来很神奇,Space Cloud就能帮我们实现这一切

Space Cloud是什么?

简而言之,Space Cloud是一个开源的Web服务器,它能在数据库和微服务之上即时提供GraphQL和REST API。

Space Cloud最酷的一点在于,所有API都是实时的。我们可以选择订阅数据库的变更。在实现实时应用时,该功能非常便利。

本指南中,我们会用Space Cloud的remote service模块将REST服务迁移成GraphQL。

架构

基于REST之上的GraphQL架构最终如下图所示:

我们的应用将会发起对Space Cloud的GraphQL查询,该请求又会访问服务器上的REST端点。在该场景中,Space Cloud会作为GraphQL代理或API网关。

你可能注意到,Space Cloud是一个单独的GraphQL层,位于REST服务之上。这种方式的优点在于REST服务依然能够保持原样,已有的客户端可以直接使用它们。这样,从REST服务迁移至GraphQL不会破坏旧的客户端。

接下来,让我们开始。

我们将要构建什么?

本指南中,我们将会构建一个简单的算数服务,它包含如下端点:

  • 求和计算端点POST /adder
  • 翻倍计算端点GET /doubler/:num

求和计算端点将会返回两个数的和,这两个数是通过请求的body获取到的。翻倍计算端点将会对其接收到的值翻倍,初始值是通过URL路径参数获取到的。

现在,开始构建

第一步:编写服务

现在,我们开始编写REST服务。在这里,我们使用NodeJS和Express来编写REST服务。

注意:你可以使用任意语言和框架来编写服务,只要它支持HTTP即可,因为这是Space Cloud用来与你的REST服务进行通信的协议。

首先,创建一个文件夹作为工作目录。

创建NPM项目

npm init -y

安装Express

npm install --save express

编写express服务器

创建名为index.js的文件,并复制粘贴如下代码:

var express = require("express");
var app = express();
app.use(express.json());
app.post("/adder", function(req, res) {
  const num1 = req.body.num1;
  const num2 = req.body.num2;
  const response = { result: num1 + num2 };
  res.status(200).send(JSON.stringify(response));
});
app.get("/doubler/:num", function(req, res) {
  const num = req.params.num;
  const response = { result: num * 2 };
  res.status(200).send(JSON.stringify(response));
});
var server = app.listen(5000, function () {
    console.log("app running on port:", server.address().port);
});

可以看到,代码非常简单直接。我们只是使用ExpressJS创建了一个HTTP服务器并监听5000端口。

如前文所示,服务器包含两个端点:

  • 求和计算端点:我们预期从POST的body中接收到两个数字,即num1num2,接下来所做的就是返回这两个数字的和。
  • 翻倍计算端点:我们将通过URL路径参数得到的数字乘以2,然后返回。

对于服务来讲,我们做这些就足够了。

第二步:启动服务

要运行服务,我们只需执行如下命令即可:

node index.js

我们让REST服务启动并运行了起来。接下来,启动Space Cloud并通过GraphQL来使用REST服务。

第三步:下载Space Cloud

我们需要为自己的操作系统下载Space Cloud二进制文件,也可以通过其源码直接进行构建。如果从源码构建的话,需要go 1.13.0或更高版本。

可以通过以下链接下载对应操作系统的二进制文件:

下载后,我们解压压缩包。

对于Linux/Macunzip space-cloud.zip && chmod +x space-cloud

对于Windows:右键点击压缩包并选择“解压到此处”。

为确保二进制文件的正确性,在二进制文件的解压目录下,运行如下命令:

对于Linux/Mac./space-cloud -v

对于Windowsspace-cloud.exe -v

它将会展现如下输出:

space-cloud-ee version 0.13.0

第四步:下载Space Cloud

要以dev模式启动Space Cloud,可以复制粘贴如下命令并点击回车键:

对于Linux/Mac./space-cloud run --dev

对于Windowsspace-cloud.exe run --dev

在Space Cloud启动时,我们会看到如下所示的输出:

Creating a new server with id auto-1T5fA9E1B2jeNUbV8R0fOPubRng
Starting http server on port: 4122

   Hosting mission control on http://localhost:4122/mission-control/

Space cloud is running on the specified ports :D

注意:--dev标记会告诉Space Cloud以dev模式运行(所以,admin UI不会要求输入用户名和密码)。

第五步:配置Space Cloud

我们注意到,Space Cloud在工作目录生成一个config.yaml文件。

Space Cloud需要该文件来完成它的功能。这个文件用来加载一些信息,包括要连接的REST服务器以及它们的端点。Space Cloud有自己的Mission Control(admin UI),借助它能够快速完成配置。

打开Mission Control

导航至http://localhost:4122/mission-control,可以打开Mission Control。

注意:如果你不是在本地Space Cloud的话,那么需要将localhost替换为实际地址。

创建项目

点击Create a Project按钮,打开如下界面:

为你的项目设置一个name

在这里选择什么数据库无关紧要,因为我们不会用到它。

点击Next创建项目。

第六步:添加远程服务到Space Cloud中

导航至Mission Control的Remote Services区域。

点击Add first remote service按钮来打开如下的表单:

将服务名设置为arithmetic,并将服务的URL设置为:

http://localhost:5000

添加完远程服务之后,在远程服务的表格中,我们应该就能看到它:

点击Actions列中的Add按钮,将会打开服务页面。

点击Add first remote endpoint按钮,打开如下所示表单:

为求和计算端点添加如下内容:

  • Name:adder
  • Method:POST
  • Path:/adder

再次点击“Add”按钮并添加doubler端点:

  • Name:doubler
  • Method:GET
  • Path:/doubler/{args.num}

注意:现在不要担心{args.num}部分,只需要确保将Method设置为GET即可。

第七步:通过GraphQL来查询REST服务

现在,我们添加了REST和两个端点到Space Cloud中,接下来,我们该使用统一的GraphQL API对其进行查询。

跳转至Explorer区域:

尝试在GraphiQL explorer中运行如下的GraphQL查询:

{
  adder(num1: 10, num2: 20) @arithmetic {
    result
  }
}

将会看到如下所示的响应:

{
  "adder": {
    "result": 30
  }
}

在得到上述GraphQL查询后,Space Cloud会向REST服务发送如下的请求:

  • Method:POST
  • Path:/adder
  • Request Body:
{
  "num1": 10,
  "num2": 20
}

这意味着我们传递给GraphQL查询的参数以Request Body的形式传递给了REST服务。

接下来,我们尝试使用如下的GraphQL查询来访问doubler端点:

{
  doubler(num: 50) @arithmetic {
    result
  }
}

GraphQL查询会被Space Cloud翻译成为对REST的调用,如下所示:

GET /doubler/50

如果你还记得的话,我们添加到Space Cloud的doubler端点是这样的:

/doubler/{args.num}

基于该端点,Space Cloud能够知道它要从GraphQL中获取一个参数num,并使用它作为变量来形成路径/doubler/50

成功调用后,我们会看到如下所示的响应:

{
  "doubler": {
    "result": 100
  }
}

额外奖励——服务链

如果成功遵循这个指南的话,我们会有一个奖励!这个REST到GraphQL的转换为我们解锁了一个超级强大的功能:服务链(Service Chaining)。

让我们来看一个场景:

  • 我们想要使用 the adder service对两个数字求和;
  • 我们想把从 the adder service得到的结果翻倍。

REST方式

如果我们在客户端代码中使用REST的话,上述任务将会如下所示:

注意,我们从前端发出两个请求,就意味着往返时间会翻倍。它会导致较慢的响应时间和较差的用户体验。

GraphQL方式

现在,如果我们将客户端从REST切换为使用Space Cloud的GraphQL,那么我们的请求将会如下所示:

注意,在这里,我们只从前端发起了一次GraphQL查询到后端(Space Cloud)。而Space Cloud发起两次请求到REST服务器以满足该请求。但是,这些请求(从Space Cloud到我们的服务器)的往返时间是微不足道的,因为它们位于同一个网络中。

要完成上述任务,到Space Cloud的GraphQL查询如下所示:

{
  adder(num1: 10, num2: 20) @arithmetic {
    doubler(num: "adder.result") @arithmetic {
      result
    }
  }
}

请注意,我们是如何在得到adder服务的响应后调用doubler服务的,而且我们将adder服务的result以参数形式传递给doubler服务。

查询结果将会如下所示:

{
  "adder": {
    "doubler": {
      "result": 60
    }
  }
}

可以猜到,我们得到的结果是60,即((10 + 20) * 2)。

小提示:如果你想并行执行两个不相关REST服务的话,我们可以在一个请求中完成,如下所示:

{
  adder(num1: 10, num2: 20) @arithmetic {
    result
  }
  doubler(num: 50) @arithmetic {
    result
  }
}

我把这个查询会得到什么响应作为作业留给读者。

结论

首先,鼓励一下自己,因为你完整地读完了该指南。

通过该指南,我们学到:

  • 从REST迁移到GraphQL不需要更改代码。
  • 我们不需要在REST和GraphQL之间进行非此即彼的选择。我们可以在同一个应用程序中同时支持REST和GraphQL。
  • 借助Space Cloud来使用GraphQL会带来网络方面的收益,有助于减少往返时间。

除了从REST迁移到GraphQL(如跨数据库连接)之外,我们还可以用Space Cloud做更多事情。

  • 发表于:
  • 本文为 InfoQ 中文站特供稿件
  • 首发地址https://www.infoq.cn/article/gpucwCoDMKuvwiHTWSOz
  • 如有侵权,请联系 yunjia_community@tencent.com 删除。

扫码关注云+社区

领取腾讯云代金券