十個書寫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