首页 ›存档› 技术 › 查看内容

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

2018-3-30 13:00 |来自: 互联网 263 0

摘要: 　　Node.js 除了用来编写 WEB 应用之外，还可以用来编写 API 服务，我们在本文中会介绍编写 Node.js Rest API 的最佳实践，包括如何命名路由、进行认证和测试等话题，内容摘要如下：正确使用 HTTP Method 和路由 ...

　　Node.js 除了用来编写 WEB 应用之外，还可以用来编写 API 服务，我们在本文中会介绍编写 Node.js Rest API 的最佳实践，包括如何命名路由、进行认证和测试等话题，内容摘要如下：

正确使用 HTTP Method 和路由
正确的使用 HTTP 状态码
使用 HTTP Header 来发送元数据
为 REST API 挑选合适的框架
要对 API 进行黑盒测试
使用基于 JWT 的无状态的认证机制
学会使用条件请求机制
拥抱接口调用频率**（Rate-Limiting）
编写良好的 API 文档
对 API 技术演化保持关注

　1. 正确使用 HTTP Method 和路由

　　试想你正要构建一个 API 用来创建、更新、获取、删除用户，对于这些操作，HTTP 规范里面已经有了现成的操作：POST、PUT、GET、DELETE，建议直接使用他们来描述接口的行为。

　　至于路由的命名，应该使用名词或名词性短语来作为资源标识符，比如上文提到的用户管理的例子，路由就应该长这样：

POST /users 或者 PUT /users/:id 用来创建新用户；
GET /users 用来获取用户列表；
GET /users/:id 用来获取单个用户；
PATCH /users/:id 用来更新用户信息；
DELETE /users/:id 用来删除用户；

　2. 正确的使用 HTTP 状态码

　　如果服务器端在请求处理的过程中出错了，你必须设置正确的响应状态码，具体如下：

2xx，表示一切正常；
3xx，表示资源位置已经更改；
4xx，表示因为客户端错误而导致请求无法被处理，比如参数校验没通过；
5xx，表示因为服务器错误导致请求无法被处理，比如服务端抛了异常；

　　如果你使用 express，设置状态码非常简单：res.status(500).send({ error: 'Internal server error happend' })，如果使用了 restify，也是类似的：res.status(201)。

　　如果想看完整的 HTTP 状态码，点击这里。

　3. 使用 HTTP Header 来发送元数据

　　如果想要发送关于响应体数据的元数据，可以使用 Header ，Header 可以包含的常见元数据包括如下几类：

分页信息；
频率**信息；
认证信息；

　　如果你需要在 Header 中发送自定义的元数据，最好的做法是在 Header 名称前面加 X，例如，需要发送 CSRF Token 的时候，实际的 Header 应该命名为：X-CSRF-Token，然而，这种 Header 在 RFC 6648 中已经被废弃了。API 在设置自定义 Header 的时候还要尽可能避免命名冲突，比如为了达到这个目的OpenStack 为所有 API 的自定义 Header 都加上了 OpenStack 的前缀：

OpenStack-Identity-Account-ID 
OpenStack-Networking-Host-Name 
OpenStack-Object-Storage-Policy

　　需要注意的是，虽然 HTTP 规范中没有规定 Header 的大小，但是 Node.js 中 Header 的大小被**在了 80KB。官方原文如下：

不要让 HTTP Header ，包括其中状态码那行的整体大小超过 HTTP_MAX_Header_SIZE，这样做的目的是为了防御基于 Header 的 DDOS 攻击。点击这里

　4. 为 REST API 挑选合适的框架

　　根据你的实际场景挑选合适的框架是非常重要的，Node.js 中的框架大致介绍如下：

　　Express、Koa、HAPI

　　Express、Koa、HAPI 主要是用来构建浏览器 WEB 应用，因为他们都支持服务端模板渲染，虽然这只是他们众多功能中的一个。如果你的应用需要提供用户界面，那么这三个就是不错的选择。

　　Restify

　　而 Restify 是专门用来创建符合 REST 规范的服务的，他诞生的目的就是帮你构建严格意义上的、可维护的 API 服务。Restify 内置了所有请求处理函数的 DTrace 支持。并且已经被 npm 和 netflix 用来在生产环境提供重要的服务。

　5. 要对 API 进行黑盒测试

　　测试 API 的最好办法是对他们进行黑盒测试，黑盒测试是一种不关心应用内部结构和工作原理的测试方法，测试时系统任何部分都不应该被 mock。

　　supertest 是可以用来对接口进行黑盒测试的模块之一，下面是基于测试框架 mocha 编写的一个测试用例，该用例的目的是检查接口是否能返回单条的用户数据：

const request = require('supertest')

describe('GET /user/:id', function() {
 it('returns a user', function() {
  // newer mocha versions accepts promises as well
  return request(app)
   .get('/user')
   .set('Accept', 'application/json')
   .expect(200, {
    id: '1',
    name: 'John Math'
   }, done);
 });
});

　　可能有人会问：API 服务所连接的数据库里面的数据是如何写进去的呢？

　　通常来说，你写测试的时候，要尽可能不对系统状态做假设，然而在某些场景下，你需要准确的知道系统当前所处的状态以增加更多的断言来提高测试覆盖率。如果你有这种需求，你可以试用如下的方法对数据库进行预填充：

选择生产环境数据的子集来运行黑盒测试；
运行黑盒测试之前把手工构造的数据填充到数据库中。

　　此外，有了黑盒测试并不意味着不需要单元测试，针对 API 的单元测试还是需要编写的。

　6. 使用基于 JWT 的无状态的认证机制

　　因为 Rest API 必须是无状态的，因此认证机制也需要是无状态的，而基于 JWT（JSON Web Token）的认证机制是无状态认证机制中的最佳解决方案。

　　JWT 的认证机制包含三部分：

Header：包含 token 的类型和哈希算法；
payload：包含声明信息；
signature：JWT 实际上并不是对 payload 进行加密，只是对其做了签名；

　　为 API 添加基于 JWT 的认证机制也非常的简单，比如下面的代码：

const koa = require('koa');
const jwt = require('koa-jwt');

const app = koa();

app.use(jwt(
 secret: 'very-secret'
}));

// Protected middleware
app.use(function*() 
 // content of the token will be available on this.state.user
 this.body = { secret: '42' }
});

　　有了如上的代码，你的 API 就有了 JWT 的保护。如果要访问这种被保护的接口，需要使用 Authorization Header 来提供 token，比如：

curl --Header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ" my-website.com

　　你可能注意到了，JWT 模块并不依赖任何数据存储层，这是因为 token 本身是可以单独被校验的，token 里面的 payload 甚至可以包含 token 的签名时间、有效期限。

　　此外，你还需要确保，所有的 API 接口只能通过更安全的 HTTPS 链接来访问。