在 Web 開發(fā)的動(dòng)態(tài)世界中,可擴(kuò)展且高效的應(yīng)用程序必須建立在 API 設(shè)計(jì)的堅(jiān)實(shí)基礎(chǔ)上。隨著對(duì) RESTful API 的需求不斷增加,Node.js 現(xiàn)已成為構(gòu)建高性能、事件驅(qū)動(dòng)的 API 來服務(wù)大量并發(fā)請(qǐng)求的強(qiáng)大力量。以下部分實(shí)際上深入研究了使用 Node.js 進(jìn)行有效 API 設(shè)計(jì)的原則,這對(duì)開發(fā)人員有很大的幫助和相關(guān)性,特別是對(duì)于那些在海得拉巴學(xué)習(xí) Java 開發(fā)課程的人。
目錄
了解 RESTful API 設(shè)計(jì)
選擇正確的 HTTP 方法
2.1 獲取、發(fā)布、放置、修補(bǔ)和刪除
2.2 將HTTP方法與CRUD操作相匹配
設(shè)計(jì)直觀的 API 端點(diǎn)
3.1 端點(diǎn)的命名約定
3.2 對(duì) API 進(jìn)行版本控制
處理請(qǐng)求和響應(yīng)
4.1 解析請(qǐng)求數(shù)據(jù)
4.2 發(fā)送適當(dāng)?shù)捻憫?yīng)
實(shí)施身份驗(yàn)證和授權(quán)
5.1 基本身份驗(yàn)證
5.2 使用 JWT 基于令牌的身份驗(yàn)證
錯(cuò)誤處理和日志記錄
6.1 返回有意義的錯(cuò)誤消息
6.2 調(diào)試日志
7.1 使用 Swagger 和 Postman
7.2 維護(hù)實(shí)時(shí)文檔
測(cè)試您的 API
8.1 使用 Mocha 和 Chai 進(jìn)行單元測(cè)試
8.2 使用 Supertest 進(jìn)行集成測(cè)試
部署您的 API
9.1 云端 Node.js API
9.2 集群和負(fù)載平衡:擴(kuò)展您的 API
良好 API 設(shè)計(jì)的最佳實(shí)踐
了解 RESTful API 設(shè)計(jì)
RESTful API 設(shè)計(jì)是指創(chuàng)建 Web 服務(wù)時(shí)的一組準(zhǔn)則和約束。 REST API 是使用 HTTP 方法的網(wǎng)絡(luò)服務(wù),可針對(duì) URI 標(biāo)識(shí)的資源進(jìn)行操作,以執(zhí)行標(biāo)準(zhǔn) CRUD 操作。這樣,無論誰實(shí)現(xiàn)這些原則,都可以得到可擴(kuò)展、可維護(hù)且易于理解的 API。
由于其事件驅(qū)動(dòng)架構(gòu)和非阻塞 I/O,Node.js 是構(gòu)建 RESTful API 的完美選擇之一。能夠同時(shí)處理大量連接并提供包含庫和框架的龐大生態(tài)系統(tǒng)是該技術(shù)在開發(fā)人員中非常受歡迎的原因。
在 HTTP 中選擇正確的方法
獲取、發(fā)布、放置、修補(bǔ)、刪除
HTTP 方法是 RESTful API 設(shè)計(jì)的基石,根據(jù)請(qǐng)求的目的一致應(yīng)用,如下所示: GET:用于讀取資源或其表示; POST:用于創(chuàng)建新資源或?qū)?shù)據(jù)發(fā)布到服務(wù)器; PUT:用于對(duì)現(xiàn)有資源進(jìn)行更新; PATCH:對(duì)現(xiàn)有資源進(jìn)行部分更新; DELETE:刪除資源。這些方法中的每一種都被一致地應(yīng)用。這是為了使客戶端能夠以可預(yù)測(cè)且直觀的方式使用 API。
將 HTTP 方法與 CRUD 操作相匹配
為了保證可讀性和一致性,必須將 HTTP 方法與其對(duì)應(yīng)的 C-R-U-D 操作相匹配:
獲取:閱讀
帖子:創(chuàng)建
PUT:更新 – 替換
補(bǔ)丁:更新 – 部分
刪除:刪除
將您的 API 操作與正確的 HTTP 方法結(jié)合起來將產(chǎn)生一個(gè)非常用戶友好且直觀的 API,使其易于理解和使用。
設(shè)計(jì)直觀的 API 端點(diǎn)
命名約定
API 端點(diǎn)應(yīng)遵循一致、清晰的設(shè)計(jì)。使用與名詞一致的名稱,這將清楚地標(biāo)識(shí)正在訪問的資源。例如,這可能如下所示:/users 表示用戶集合,/users/:id 表示單個(gè)用戶。避免使用動(dòng)詞命名端點(diǎn),因?yàn)?via the
HTTP方法,很清楚正在執(zhí)行什么操作。集合將使用名詞的復(fù)數(shù)形式和單數(shù)來命名
代表單個(gè)資源時(shí)的名詞形式。
您需要對(duì)此 API 進(jìn)行版本控制,以便在您改進(jìn) API 時(shí),早期版本會(huì)繼續(xù)運(yùn)行并且不會(huì)因更改而中斷。確保使用非常一致的版本控制方案來指示 API 的版本,例如 /v1/users、/api/v1/users,…
在進(jìn)行重大更改時(shí),引入新版本的 API 并貶值舊版本。這樣,客戶可以按照自己的節(jié)奏遷移到新版本,而舊版本仍將保持功能。
處理請(qǐng)求和響應(yīng)
解析請(qǐng)求數(shù)據(jù)
始終解析和驗(yàn)證傳入數(shù)據(jù),以確認(rèn)其在 API 中的適用性。正文解析中間件有助于解析 JSON 格式的傳入請(qǐng)求正文。 ?
使用 Joi 或驗(yàn)證器等庫根據(jù) API 架構(gòu)和業(yè)務(wù)規(guī)則驗(yàn)證傳入數(shù)據(jù)。這減少了潛在的錯(cuò)誤并確保數(shù)據(jù)完整性。
?
返回適當(dāng)?shù)幕貜?fù)
確保您的響應(yīng)返回適當(dāng)?shù)?HTTP 狀態(tài)代碼來指示請(qǐng)求的結(jié)果,例如:200 OK 表示 GET 請(qǐng)求成功,201 Created 表示成功的 POST 請(qǐng)求,204 No Content 表示成功的 DELETE 請(qǐng)求。
以 JSON 形式返回?cái)?shù)據(jù),并與 API 中的響應(yīng)結(jié)構(gòu)保持一致。添加有關(guān)分頁信息或錯(cuò)誤消息的附加元數(shù)據(jù),為客戶端提供上下文。
實(shí)現(xiàn)身份驗(yàn)證和授權(quán)
基本身份驗(yàn)證
基本身份驗(yàn)證是使用用戶名和密碼對(duì)客戶端進(jìn)行身份驗(yàn)證的最簡(jiǎn)單方法。它很容易安裝,但不適合生產(chǎn)使用,因?yàn)樗话魏伟踩δ堋J褂?JWT 基于令牌的身份驗(yàn)證
JSON Web 令牌比基本身份驗(yàn)證更安全且可擴(kuò)展。 JWT通過發(fā)布包含用戶信息和權(quán)限的簽名令牌來實(shí)現(xiàn)客戶端的身份驗(yàn)證和授權(quán)。
當(dāng)客戶端使用您的 API 進(jìn)行身份驗(yàn)證時(shí),返回 JWT;后者將在后續(xù)請(qǐng)求中包含此令牌。在服務(wù)器端,驗(yàn)證token的簽名,以了解它是否有效或已被篡改。
錯(cuò)誤處理和日志記錄
一定要返回有意義的錯(cuò)誤消息
如果出現(xiàn)任何錯(cuò)誤,它應(yīng)該向客戶端返回有意義的錯(cuò)誤消息,其中包含足夠的信息用于診斷和解決問題。為錯(cuò)誤類型設(shè)置正確的 HTTP 狀態(tài)代碼:400 Bad Request 表示客戶端錯(cuò)誤,500 Internal Server Error 表示服務(wù)器端錯(cuò)誤。
包含每條相關(guān)錯(cuò)誤信息:例如,錯(cuò)誤代碼、消息以及響應(yīng)正文可能包含的任何其他上下文。包含此類信息可能會(huì)幫助客戶識(shí)別出了什么問題以及如何修復(fù)它。
用于調(diào)試和監(jiān)控的日志記錄
在應(yīng)用程序中設(shè)置良好的日志記錄機(jī)制,以記錄執(zhí)行過程中的錯(cuò)誤、警告和重要事件。使用好的日志庫,如 morgan 或 Winston,來記錄請(qǐng)求/響應(yīng)/錯(cuò)誤。
將日志保存在一個(gè)位置(文件或日志記錄服務(wù)),以便于調(diào)試和監(jiān)控。然后,設(shè)置日志級(jí)別來處理重要消息并忽略多余的噪音。
記錄你的API
使用Swagger和Postman等工具
為 API 制作完整的文檔,以便所有遇到它的用戶都知道如何使用它。使用 Swagger 和 Postman 等工具的自動(dòng)化交互式文檔為您提供端點(diǎn)、請(qǐng)求、響應(yīng)示例,甚至有關(guān)如何進(jìn)行身份驗(yàn)證的詳細(xì)信息。保持文檔更新并遵循 API 中所做的更改,以確保客戶端擁有有關(guān)端點(diǎn)及其使用情況的有效信息。
定期更新 API 文檔以跟上 API 的更改或添加也很重要。可以為每個(gè)新功能或編輯的增強(qiáng)功能啟動(dòng)文檔更新過程。
您甚至可以為您的文檔設(shè)計(jì)一個(gè)版本控制系統(tǒng)。這意味著您的客戶將能夠根據(jù)其 API 版本查看文檔的版本。
測(cè)試您的 API
使用 Mocha 和 Chai 進(jìn)行單元測(cè)試
使用單元測(cè)試來測(cè)試 API,以驗(yàn)證單個(gè)組件是否按預(yù)期工作。您可以使用 Mocha 和 Chai 等測(cè)試框架編寫和運(yùn)行測(cè)試。
為所有端點(diǎn)編寫測(cè)試,確保針對(duì)不同的輸入場(chǎng)景返回正確的響應(yīng)。檢查邊緣情況和錯(cuò)誤條件,以確保您的 API 能夠妥善處理它們。
與 Supertest 集成測(cè)試
編寫集成測(cè)試來確保 API 的所有部分協(xié)調(diào)工作也同樣重要。 Supertest 是一個(gè)優(yōu)秀的庫,用于向 API 發(fā)送 HTTP 請(qǐng)求并測(cè)試響應(yīng)。
典型的用例場(chǎng)景應(yīng)該有測(cè)試。創(chuàng)建用戶、登錄或更新配置文件都應(yīng)該是測(cè)試套件的一部分。通過這種方式,您將確信您的端點(diǎn)能夠很好地相互協(xié)作,并且所有一切作為一個(gè)整體都能夠正常運(yùn)行。
部署您的API
如何托管 Node.js API
根據(jù)您的需求和您有多少錢,您可以在托管 Node.js API 時(shí)使用以下其中一種:PaaS 或平臺(tái)即服務(wù):這包括 Heroku、DigitalOcean 和 AWS Elastic Beanstalk。所有這些服務(wù)都提供了一個(gè)托管環(huán)境來部署 API。 IaaS(即基礎(chǔ)設(shè)施即服務(wù))涉及 AWS EC2、Google Compute Engine 和 DigitalOcean Droplets 等服務(wù),可讓您在虛擬機(jī)上部署 API。
將通過 AWS Lambda、Google Cloud Functions 和 Azure Functions 等服務(wù)提供無服務(wù)器敏捷性,從而促進(jìn) API 部署。
一方面考慮您的所有 API 需求和要求,另一方面考慮團(tuán)隊(duì)的專業(yè)知識(shí)和資源之間的最佳匹配,然后選擇合適的托管選項(xiàng)。
通過集群和負(fù)載均衡擴(kuò)展您的 API
隨著您的 API 越來越受歡迎和使用,擴(kuò)展性成為一個(gè)熱切關(guān)注的問題。使用 Node.js 中內(nèi)置的集群模塊,創(chuàng)建多個(gè)可以并發(fā)處理傳入請(qǐng)求的工作進(jìn)程。
為傳入請(qǐng)求實(shí)現(xiàn)負(fù)載平衡,將調(diào)用分發(fā)到 API 的多個(gè)實(shí)例。負(fù)載均衡器可以使用 Nginx 和 HAProxy 來完成。
API 設(shè)計(jì)的最佳實(shí)踐
遵循這些最佳實(shí)踐,使用 Node.js 開發(fā)一組有效的 RESTful API:
構(gòu)建一個(gè)簡(jiǎn)單且一致的 API。這意味著使用非常具有描述性并遵循一致的命名約定的端點(diǎn)名稱。
確保使用正確的 HTTP 方法。如果您確保 HTTP 方法映射到其相應(yīng)的 CRUD 操作,您可以使您的 API 直觀且易于其他人使用。
輸入驗(yàn)證和清理:在將傳入數(shù)據(jù)放入 API 之前對(duì)其進(jìn)行驗(yàn)證和清理。
優(yōu)雅地處理錯(cuò)誤:使用適當(dāng)?shù)?HTTP 狀態(tài)代碼以有意義的錯(cuò)誤消息響應(yīng)進(jìn)行響應(yīng),并記錄這些錯(cuò)誤以進(jìn)行調(diào)試和監(jiān)控。
實(shí)現(xiàn)身份驗(yàn)證和授權(quán)。使用安全的身份驗(yàn)證方法,例如 JWT,并實(shí)施授權(quán)來規(guī)范 API 任何資源的訪問控制。
記錄您的 API:提供全面的文檔,其中包含端點(diǎn)的描述、請(qǐng)求和響應(yīng)的示例以及身份驗(yàn)證詳細(xì)信息。
測(cè)試您的 API:經(jīng)過測(cè)試的 API 一定能按預(yù)期工作,同時(shí)捕獲開發(fā)過程早期發(fā)生的任何回歸。您可以通過單元測(cè)試和集成測(cè)試來做到這一點(diǎn)。
監(jiān)控您的腳本:可觀察性是了解 API 中的性能、使用情況和錯(cuò)誤的關(guān)鍵,可以最終快速解決問題。
通過這樣做,編寫一個(gè)有效的、可擴(kuò)展的、可維護(hù)的 RESTful API 來滿足您的客戶和用戶的需求。
總結(jié)
希望對(duì)現(xiàn)代 Web 應(yīng)用程序進(jìn)行有效編程的開發(fā)人員必須學(xué)習(xí)如何使用 Node.js 最好地設(shè)計(jì) API。了解指導(dǎo) RESTful API 設(shè)計(jì)的原則以及 Node.js 的強(qiáng)大功能,使開發(fā)人員能夠創(chuàng)建高度可擴(kuò)展、可維護(hù)且用戶友好的 API。
對(duì)于在海得拉巴尋找 Java 開發(fā)課程的學(xué)生來說,這是他們可以追求的非常重要的技能之一,這為大量的職業(yè)選擇打開了大門。鑒于市場(chǎng)對(duì)熟練 Node.js 開發(fā)人員的需求不斷增加,設(shè)計(jì)和有效提出 RESTful API 的能力將成為就業(yè)市場(chǎng)的關(guān)鍵差異化因素。
通過擁抱 API 設(shè)計(jì)的工藝和藝術(shù)并不斷練習(xí)以達(dá)到精通,開發(fā)人員可以帶來創(chuàng)造性的解決方案,繼續(xù)挑戰(zhàn)網(wǎng)絡(luò)的極限。在技??術(shù)從日出到日落的變化中,使用 Node.js 進(jìn)行正確的 API 設(shè)計(jì)將在未來的可擴(kuò)展和響應(yīng)式應(yīng)用程序開發(fā)中發(fā)揮巨大的基礎(chǔ)作用。