十个书写Node.js REST API的最佳实践（上）

收录待用，修改转载已取得腾讯云受权

---

原文：10 Best Practices for Writing Node.js REST APIs

咱们会经过本文介绍下书写Node.js REST API的最佳实践，包括各个主题，像是命名路由、认证、黑盒测试以及对相关资源使用合适的缓存头。

对于Node.js来讲最流行的一个用例就是用其来书写RESTful API。尽管如此，当咱们使用监控工具来帮助用户排查问题时，咱们老是能感觉到在REST API上开发者们有不少的问题。

我但愿这些最佳实践可以对你有所帮助。

1. 使用HTTP方法和API路由

设想一下你正在构建Node.js RESTful API用以用来建立、更新、获取或者删除用户。这些操做HTTP已经有能够胜任的工具集：POST,PUT, GET, PATCH 或 DELETE。

做为最佳实践，你的API路由应该一直使用名词做为资源id。涉及到用的资源相关的，路由机制也能够这样：

• POST /user 或者 PUT /user:/id 来建立新用户

• GET /user 来获取列表的用户

• GET /user/:id 来得到某一个用户

• PATCH /user/:id 来修改已有的用户记录

• DELETE /user/:id 来删除一个用户

2. 正确地使用HTTP状态码

若是处理请求时出了问题，你必须在响应里设置正确的状态码：

• 2xx，若是一切都ok

• 3xx，若是资源被移除

• 4xx，若是由于服务器错误致使请求没法实现 (例如请求一个不存在的资源)

• 5xx, 若是API测出现问题 (例如异常发生)

若是你正在使用Express，设置状态码就是这么简单 res.status(500).send({error: 'Internal server error happened'})。 和使用Restify很相似：res.status(201).

查看list of HTTP status codes以寻求完整列表

3.使用HTTP头来设置Medata

使用HTTP头把metadata加到要发送的负载上。像这样的头能够是在以下信息的上：

• 页码

• 速率限制

• 或者是认证.

标准化HTTP头的列表能够在 这里 被找到。

若是你须要在你的相应头里面设置任何自定义的metadata，给它们加上X前缀是最佳实践。例如，以前若是你在使用CSRF token时，把其命名为X-Csrf-Token是很广泛（但不标准）的作法。不管如何随着RFC 6648的发布，这些都已经被废弃了。新API最好不要使用会和其余应用发生冲突的header名。例如，OpenStack在它们的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，这会致使嵌入机一直缓冲”

来自 Node.js HTTP 解析器

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

挑选最适合你用例的框架是很重要的。

Express， Koa 亦或是 Hapi

Express，Koa和Hapi 能够被用来创造浏览器应用，一样的，它们支持模版和渲染 —— 只须要来命名几个特性。若是你的应用也须要提供用户界面，使用它们颇有必要。

Restify

另外一方面，Restify致力于帮助你构建REST服务。其存在的意思便在于让你构建“严格的”可维护可观察的API服务。Restify一样能够和自动化的DTrace协做支持你全部的handler。

Restify主要被用于像npm或者Netflix的应用生产里。

接下篇《十个书写Node.js REST API的最佳实践（下）》

---

原文连接：https://www.qcloud.com/community/article/266459