主页»NodeJS»编写 Node.js Rest API 的 10 个最佳实践

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

来历:王仕军 发布时刻:2017-03-03 阅览次数:

  Node.js 除了用来编写 WEB 运用之外,还能够用来编写 API 服务,咱们在本文中会介绍编写 Node.js Rest API 的最佳实践,包括怎么命名路由、进行认证和测验等论题,内容摘要如下:

  1. 正确运用 HTTP Method 和路由
  2. 正确的运用 HTTP 状况码
  3. 运用 HTTP Header 来发送元数据
  4. 为 REST API 挑选适宜的结构
  5. 要对 API 进行黑盒测验
  6. 运用依据 JWT 的无状况的认证机制
  7. 学会运用条件恳求机制
  8. 拥抱接口调用频率约束(Rate-Limiting)
  9. 编写杰出的 API 文档
  10. 对 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

  ExpressKoaHAPI 主要是用来构建浏览器 WEB 运用,由于他们都支撑服务端模板烘托,尽管这仅仅他们很多功用中的一个。假如你的运用需求供给用户界面,那么这三个便是不错的挑选。

  Restify

  而 Restify 是专门用来创立契合 REST 标准的服务的,他诞生的意图便是帮你构建严厉意义上的、可维护的 API 服务。Restify 内置了一切恳求处理函数的 DTrace 支撑。而且现已被 npmnetflix 用来在出产环境供给重要的服务。

 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 的认证机制包括三部分:

  1. Header:包括 token 的类型和哈希算法;
  2. payload:包括声明信息;
  3. 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 链接来拜访。

 7. 学会运用条件恳求机制

  条件恳求机制是依据不同的 Header 表现出不同的行为的机制,能够以为这些 Header 便是恳求处理方式的先决条件,假如条件满意,恳求处理方式就会有所不同。

  能够运用这些 Header 检测服务器上的资源版别是否匹配特定的资源版别,这些 Header 的取值能够是如下的内容:

  • 资源的最终修正时刻;
  • 资源的标签(随资源改变而改变);

  详细来说:

  • Last-Modified:标识资源的最新修正时刻;
  • Etag:标识资源的标签;
  • If-Modified-Since:结合 Last-Modified Header 运用;
  • If-Non-Match:结合 Etag 运用;

  下面来看一个实践的比方:

  客户端不知道 doc 资源的任何版别,所以恳求时即不能供给 If-Modified-Since,也不能供给 If-Non-Match 两个 Header,然后服务端在呼应中会添加 Etag 和 Last-Modified 两个 Header。

  nodejs-resftul-api-with-conditional-request-without-previous-versions.png

  接下来,客户端再次恳求相同的资源的时分,就能够带上 If-Modified-Since 和 If-Non-Match 这两个 Header 了,然后假如服务器端会查看资源是否修正,假如没有修正,直接回来 304 - Not Modified 状况码,而不重复发送资源的内容。

  nodejs-resftul-api-with-conditional-request-with-previous-versions.png

 8. 拥抱接口调用频率约束(Rate-Limiting)

  频率约束是用来操控调用方有对接口主张恳求的次数,为了让你的 API 用户知道他们还剩下多少余额,能够设置下面的 Header:

  • X-Rate-Limit-Limit:特定时刻段内答应的最多恳求次数;
  • X-Rate-Limit-Remaining:特定时刻段内剩下的恳求次数;
  • X-Rate-Limit-Reset:什么时分恳求频率约束次数会重置;

  大多数的 WEB 结构都支撑上面这些 Header,假如内置不支撑,也能够找到插件来支撑,比方,假如你运用了 koa,能够运用 koa-rate-limit

  需求留意的是,不同的 API 服务供给商频率约束的时刻窗差异会很大,比方 GitHub 是 60 分钟,而 Twitter 是 15 分钟。

 9. 编写杰出的 API 文档

  编写 API 的意图当然是让他人运用并获益,供给杰出的接口文档至关重要。下面这两个开源项目能够帮你创立 API 文档:

  假如你乐意运用第三方文档服务商,能够考虑 Apiary

 10. 对 API 技能演化坚持重视

  曩昔几年中,API 技能计划范畴呈现了两种新的查询言语,分别是 Facebook 的 GraphQL 和 Netflix 的 Falcor,为什么需求他们呢?

  试想这种 API 接口恳求:/org/1/space/2/docs/1/collaborators?include=email&page=1&limit=10,相似的状况会让 API 很快失控,假如你期望一切接口能回来相似的呼应格局,那么 GraphQL 和 Falcor 就能帮你处理这个问题。

  关于 GraphQL

GraphQL 是一种用于 API 的查询言语,也是一种依据现有数据处理数据查询的运转时。GraphQL 为您的 API 中的数据供给了一个完好和可了解的描绘,运用户能够精确地问询他们需求什么,使得跟着时刻推移的 API 演化更简单,GraphQL 还有强壮的开发东西支撑。 到这儿阅览更多。

  关于 Falcor

Falcor 是支撑着 Netflix UI 的立异数据渠道。Falcor 答应你将一切后端数据建模为 Node.js 服务商的单个虚拟 JSON 目标。在客户端能够运用了解的 JavaScript 操作、处理长途JSON目标。假如你知道你的数据,你就知道你的 API 长啥样。 到这儿阅览更多。

 能带来创意的优异 API 规划

  假如你正在开发 Rest API 或许预备改善老版别的 API,这儿搜集了几个在线上供给服务、规划优异而且十分直接学习的 API:

  期望读到这儿的同学对怎么用 Node.js 编写杰出的 API 有更好的了解,假如有主张,欢迎谈论中提出。

  英文原文:https://blog.risingstack.com/10-best-practices-for-writing-node-js-rest-apis/

QQ群:凯发娱乐官网官方群(515171538),验证音讯:10000
微信群:加小编微信 849023636 邀请您参加,验证音讯:10000
提示:更多精彩内容重视微信大众号:全栈开发者中心(fsder-com)
网友谈论(共2条谈论) 正在载入谈论......
沉着谈论文明上网,回绝歹意咒骂 宣布谈论 / 共2条谈论
登录会员中心