使用 HTTP 方法和 API 路由

在設(shè)計(jì) RESTful API 時(shí)，合理使用 HTTP 方法（如 POST、PUT、GET、PATCH 和 DELETE）是關(guān)鍵。每種方法對(duì)應(yīng)特定的操作：

此外，API 路由應(yīng)始終使用名詞作為資源標(biāo)識(shí)符，而非動(dòng)詞。例如，創(chuàng)建用戶的路由應(yīng)為 POST /user，而非 POST /createUser。

正確使用 HTTP 狀態(tài)碼

在處理請(qǐng)求時(shí)，返回正確的 HTTP 狀態(tài)碼可以幫助客戶端快速了解請(qǐng)求的結(jié)果：

在 Express 中，可以通過(guò)以下方式設(shè)置狀態(tài)碼：

res.status(500).send({ error: '發(fā)生了內(nèi)部服務(wù)器錯(cuò)誤' });

此外，可以通過(guò) HTTP 頭部附加元數(shù)據(jù)，例如資源的緩存信息或版本信息。

為 Node.js REST API 選擇合適的框架

根據(jù)項(xiàng)目需求選擇適合的框架至關(guān)重要。以下是一些常見(jiàn)的框架：

選擇框架時(shí)，應(yīng)根據(jù)項(xiàng)目的復(fù)雜性、團(tuán)隊(duì)的技術(shù)棧以及性能需求進(jìn)行權(quán)衡。

黑盒測(cè)試你的 Node.js REST API

黑盒測(cè)試是一種在不了解應(yīng)用程序內(nèi)部結(jié)構(gòu)的情況下驗(yàn)證功能的方法。它可以確保 API 的整體行為符合預(yù)期，而無(wú)需模擬或刪除依賴關(guān)系。

以下是一個(gè)使用 supertest 和 mocha 進(jìn)行黑盒測(cè)試的示例：

const request = require('supertest');
describe('GET /user/:id', function () {
 it('returns a user', function (done) {
 request(app)
 .get('/user/1')
 .set('Accept', 'application/json')
 .expect(200, { id: '1', name: 'John Doe' }, done);
 });
});

在測(cè)試中，盡量減少對(duì)系統(tǒng)狀態(tài)的假設(shè)。如果需要，可以通過(guò)以下方式填充測(cè)試數(shù)據(jù)：

執(zhí)行基于 JWT 的無(wú)狀態(tài)身份驗(yàn)證

REST API 通常是無(wú)狀態(tài)的，因此身份驗(yàn)證也應(yīng)無(wú)狀態(tài)。JSON Web Token (JWT) 是一種理想的解決方案。JWT 由以下三部分組成：

  1. Header：包含令牌類型和加密算法。
  2. Payload：包含用戶信息和其他聲明。
  3. Signature：用于驗(yàn)證令牌的真實(shí)性。

以下是一個(gè)簡(jiǎn)單的 JWT 實(shí)現(xiàn)示例：

const jwt = require('jsonwebtoken');
const token = jwt.sign({ id: 1, name: 'John Doe' }, 'your-secret-key', { expiresIn: '1h' });

在訪問(wèn)受保護(hù)的端點(diǎn)時(shí)，客戶端需要在 Authorization 頭部中提供令牌。

使用有條件請(qǐng)求

有條件請(qǐng)求通過(guò)特定的 HTTP 頭部（如 If-Modified-Since 和 If-None-Match）來(lái)優(yōu)化資源的傳輸。例如：

以下是一個(gè)示例流程：

  1. 客戶端首次請(qǐng)求資源時(shí)，服務(wù)器返回資源及其版本信息（如 ETag）。
  2. 客戶端再次請(qǐng)求時(shí)，附帶版本信息。如果資源未修改，服務(wù)器返回 304 Not Modified，而非完整的資源。

接受速率限制

速率限制用于控制 API 的請(qǐng)求頻率，防止濫用。可以通過(guò)以下 HTTP 頭部告知客戶端剩余的請(qǐng)求額度：

通過(guò)速率限制，可以有效保護(hù) API 的穩(wěn)定性。

創(chuàng)建正確的 API 文檔

清晰的 API 文檔能夠幫助開(kāi)發(fā)者快速上手并正確使用您的 API。以下工具可以幫助生成文檔：

確保文檔包含所有端點(diǎn)的詳細(xì)說(shuō)明、示例請(qǐng)求和響應(yīng)。

不要錯(cuò)過(guò) API 的未來(lái)

近年來(lái)，GraphQL 和 Falcor 等查詢語(yǔ)言逐漸流行。它們通過(guò)定義類型和字段，提供了更靈活的查詢方式。例如，GraphQL 允許客戶端僅請(qǐng)求所需的數(shù)據(jù)，從而避免冗余。

以下是一個(gè)簡(jiǎn)單的 GraphQL 查詢示例：

{
 user(id: "1") {
 name
 email
 }
}

相比傳統(tǒng) REST API，這些查詢語(yǔ)言在復(fù)雜數(shù)據(jù)場(chǎng)景下具有顯著優(yōu)勢(shì)。

總結(jié)

通過(guò)遵循以上 10 個(gè)最佳實(shí)踐，您可以顯著提升 Node.js REST API 的質(zhì)量和用戶體驗(yàn)。從合理使用 HTTP 方法到采用現(xiàn)代化的查詢語(yǔ)言，每一步都能幫助您構(gòu)建高效、可維護(hù)的 API。如果您有其他建議或問(wèn)題，歡迎分享！

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

上一篇：

獲取Favicon網(wǎng)站圖標(biāo)API：技術(shù)實(shí)現(xiàn)與應(yīng)用指南

下一篇：

小米開(kāi)放平臺(tái)集成全攻略：開(kāi)發(fā)、測(cè)試與優(yōu)化
#你可能也喜歡這些API文章!

我們有何不同？

API服務(wù)商零注冊(cè)

多API并行試用

數(shù)據(jù)驅(qū)動(dòng)選型，提升決策效率

查看全部API→
??

熱門(mén)場(chǎng)景實(shí)測(cè)，選對(duì)API

#AI文本生成大模型API

對(duì)比大模型API的內(nèi)容創(chuàng)意新穎性、情感共鳴力、商業(yè)轉(zhuǎn)化潛力

25個(gè)渠道
一鍵對(duì)比試用API 限時(shí)免費(fèi)

#AI深度推理大模型API

對(duì)比大模型API的邏輯推理準(zhǔn)確性、分析深度、可視化建議合理性

10個(gè)渠道
一鍵對(duì)比試用API 限時(shí)免費(fèi)