编写Node.js REST API的10个最佳实践

我们介绍了编写Node.js REST API的最佳实践，包括命名路由，身份验证，黑盒测试和为这些资源使用适当的缓存头。

Node.js最受欢迎的用例之一是使用它编写RESTful API。尽管我们帮助我们的客户在Trace的应用程序中找到问题，我们的Node.js监控工具，我们不断地经历开发人员有很多REST API的问题。

我希望这些在RisingStack使用的最佳实践可以帮助：

使用HTTP方法和API路由

想象一下，您正在构建一个用于创建，更新，检索或删除用户的Node.js RESTful API。对于这些操作HTTP已经有足够的工具：POST，PUT，GET，PATCH或DELETE。

作为最佳做法，您的API路由应始终使用名词作为资源标识符。说到用户的资源，路由可以看起来像这样：

POST /user或PUT /user:/id创建新用户，

GET /user 以检索用户列表，

GET /user/:id 以检索用户，

PATCH /user/:id 修改现有用户记录，

DELETE /user/:id 删除用户。

正确使用HTTP状态代码

如果在提交请求时发生错误，您必须在响应中为此设置正确的状态代码：

2xx，如果一切都好，

3xx，如果资源被移动，

4xx，如果由于客户端错误（例如请求不存在的资源）而无法满足请求，

5xx，如果在API端发生错误（如发生异常）。

如果您使用Express，设置状态代码就像res.status(500).send({error: 'Internal server error happened'})。与Restify类似：res.status(201)。

使用HTTP标头来传送中继资料

要附加有关要发送的有效内容的元数据，请使用HTTP标头。这样的标题可以是以下信息：

分页，

速率限制，

或认证。

可以在此处找到标准化HTTP标头的列表。

如果您需要在标头中设置任何自定义元数据，那么最好将其作为前缀X。例如，如果您使用CSRF令牌，那是常见的（但不是标准的）命名方式X-Csrf-Token。但是对于RFC 6648，它们已被弃用。新API应尽最大努力不要使用可能与其他应用程序冲突的标题名称。例如，OpenStack的标头前缀为OpenStack：

请注意，HTTP标准没有定义头的任何大小限制; 然而，Node.js（写作本文时）对头对象施加了80KB的大小限制，这是出于实际原因。

“不允许HTTP头（包括状态行）的总大小超过HTTP_MAX_HEADER_SIZE这个检查是为了保护嵌入者免受拒绝服务攻击，攻击者向我们提供一个永不停止的头，嵌入器保持缓冲“。

为您的Node.js REST API选择正确的框架

重要的是选择最适合您的用例的框架。

Express，Koa或Hapi

Express，Koa和Hapi可以用于创建浏览器应用程序，因此，它们支持模板化和渲染 - 仅列出几个功能。如果你的应用程序还需要提供面向用户的一面，那么它们是有意义的。

另一方面，Restify专注于帮助您构建REST服务。它存在，让您构建可维护和可观察的“严格”API服务。Restric还附带了对所有处理程序的自动DTrace支持。

Restify在主要应用程序（如npm或Netflix）中用于生产。

Black-Box测试您的Node.js REST API

测试REST API的最好方法之一是将它们视为黑盒。

黑盒测试是一种测试应用程序的功能在不知道其内部结构或工作的情况下进行测试的方法。所以没有一个依赖项被嘲笑或存根，但是系统作为一个整体被测试。

可以帮助您进行黑盒测试的一个模块Node.js REST API是最高级的。

使用测试运行器mocha检查用户是否返回的简单测试用例可以这样实现：

您可能会问：数据如何填充到为REST API提供服务的数据库中？

一般来说，编写测试的方法是尽可能少地假设系统的状态。不过，在某些情况下，当你需要知道系统的状态是什么时，你可以发现自己在一个地方，所以你可以做断言并获得更高的测试覆盖率。

因此，根据您的需要，您可以使用以下方法之一来使用测试数据填充数据库：

在生产数据的已知子集上运行您的黑盒测试场景，

在测试用例运行之前，用精制数据填充数据库。

当然，黑盒测试并不意味着你不必进行单元测试，你仍然必须为你的API 编写单元测试。

做基于JWT，无状态认证

由于您的REST API必须是无状态的，因此您的身份验证层也是如此。为此，JWT （JSON Web Token）是理想的。

JWT由三部分组成：

头，包含令牌的类型和散列算法

有效载荷，包含索赔

签名 （JWT不加密有效负载，只是签名！）

向您的应用程序添加基于JWT的身份验证非常简单：

之后，使用JWT保护API端点。要访问受保护的端点，您必须在Authorization标题字段中提供令牌。

JWT令牌都可以自己验证，并且它们还可以包含生存值的时间。

此外，您始终必须确保所有API端点只能通过使用HTTPS的安全连接访问。

使用条件请求

条件请求是根据特定HTTP头执行不同的HTTP请求。你可以认为这些头作为前提条件：如果它们被满足，请求将以不同的方式执行。

这些头试图检查存储在服务器上的资源的版本是否匹配相同资源的给定版本。因为这个原因，这些头可以是：

最后一次修改的时间戳，

或实体标签，其对于每个版本而不同。

这些标题是：

Last-Modified （以指示资源何时被最后修改），

Etag （以指示实体标签），

If-Modified-Since （与Last-Modified标头一起使用），

If-None-Match （与Etag标头一起使用），

让我们来看一个例子！

下面的客户端没有doc资源的任何先前版本，因此在资源发送时既不应用头If-Modified-Since，也不If-None-Match应用头。然后，服务器响应Etag和Last-Modified正确设置的头。

从MDN条件请求文档

客户端可以在尝试请求相同资源时设置If-Modified-Since和If-None-Match标头，因为它现在有一个版本。如果响应是相同的，服务器只是响应304 - Not Modified状态，不再发送资源。

拥抱率限制

速率限制用于控制给定用户可以向API发送多少请求。

要告知您的API用户有多少请求，请设置以下标题：

X-Rate-Limit-Limit，在给定时间间隔中允许的请求数

X-Rate-Limit-Remaining，在同一间隔中剩余的请求数，

X-Rate-Limit-Reset，速率限制将被重置的时间。

大多数HTTP框架支持它（或与插件）。例如，如果您使用Koa，则有koa-ratelimit包。

注意，时间窗口可以根据不同的API提供商而变化 - 例如，GitHub使用一个小时，而Twitter 15分钟。

创建正确的API文档

您编写API，以便其他人可以使用它们，从中受益。为您的Node.js RESTAPI提供API文档至关重要。

以下开源项目可以帮助您为API创建文档：

或者，如果您想使用托管产品，您可以去Apiary。

不要错过API的未来

在过去几年中，出现了两种主要的API查询语言 - 从Facebook的GraphQL和Netflix的Falcor。但为什么我们甚至需要他们呢？

想象下面的RESTful资源请求：

/org/1/space/2/docs/1/collaborators?include=email&page=1&limit=10

这可以很容易脱离手，因为你想要得到所有的模型所有的时间相同的响应格式。这是GraphQL和Falcor可以帮助。

关于GraphQL

GraphQL是一种用于API的查询语言，也是一种使用现有数据完成这些查询的运行时。GraphQL为您的API中的数据提供了一个完整和可理解的描述，使客户能够准确地询问他们需要什么，不再需要任何东西，使得随着时间的推移更容易演化API，并支持强大的开发工具。

关于Falcor

Falcor是支持Netflix UI的创新数据平台。Falcor允许您将所有后端数据建模为节点服务器上的单个虚拟JSON对象。在客户端上，使用熟悉的JavaScript操作（如get，set和call）处理远程JSON对象。如果你知道你的数据，你就知道你的API。