Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. Node.js
Code

使用 NodeJS 和 Restify 進行 RESTful API 設計

by
Difficulty:IntermediateLength:LongLanguages:

Chinese (Traditional) (中文(繁體)) translation by Fuhuan (you can also view the original English article)

Final product image
What You'll Be Creating

RESTful API 包含兩個主要概念:Resource 和 Representation。 資源可以是與數據關聯的任何對象,也可以用 URI 標識(多個 URI 可以引用相同的資源),並且可以使用 HTTP 方法進行操作。  表示是顯示資源的方式。 在本教程中,我們將介紹有關 RESTful API 設計的壹些理論信息,並使用 NodeJS 實現示例博客應用程序 API。

資源

為 RESTful API 選擇正確的資源是很重要的。 首先,妳需要分析妳的業務領域,然後確定將使用與妳的業務需求相關的資源數量和類型。  如果妳正在設計博客 API,則可能會使用文章,用戶和評論。 這些是資源名稱,與之關聯的數據是資源本身:

資源動詞

確定所需資源後,可以繼續執行資源操作。 這裏的操作是指 HTTP 方法。 例如,要創建文章,妳可以發出以下請求:

以同樣的方式,妳可以通過發出以下請求來查看現有文章:

更新現有文章怎麽樣? 我聽說妳說的是:

我可以使用有效負載向 / articles / update / 123456789012 發出另壹個 POST 請求。

也許更好壹些,但 URI 變得越來越復雜。 如前所述,操作可以引用 HTTP 方法。 這意味著,在 HTTP 方法中聲明更新操作,而不是將其放在 URI 中。 例如:

順便說壹下,在這個例子中,妳可以看到標簽和類別字段。 那些不需要是必填的。 妳可以將它們留空並將來設置它們。

有時,妳需要在文章過期時刪除它。 在這種情況下,妳可以對 / articles / 123456789012 使用 DELETE HTTP 請求。

HTTP 方法是標準概念。 如果妳將它們用作操作,妳將擁有簡單的 URI,這種簡單的 API 接口將幫助妳獲得客戶。

如果想在文章中插入評論怎麽辦? 可以選擇文章並為所選文章添加新評論。 通過使用此語句,可以使用以下請求:

上述形式的資源稱為子資源。 評論是文章的子資源。 上面的 Comment 有效負載將作為 Article 的子項插入數據庫中。  有時,不同的 URI 引用相同的資源。 例如,要查看特定註釋,可以使用以下任壹方法:

或者:

版本

通常,API 功能會經常更改,以便為消費者提供新功能。 在這種情況下,同壹 API 的兩個版本可以同時存在。  為了分離這兩個功能,妳可以使用版本控制。 版本控制有兩種形式

  1. URI 中的版本:妳可以在 URI 中提供版本號。 例如,/ v1.1 / articles123456789012。
  2. 標題中的版本:在標題中提供版本號,並且永遠不會更改 URI。 例如:

實際上,版本僅更改資源的表示,而不更改資源的概念。 因此,妳無需更改 URI 結構。 在 v1.1 中,可能會在 Article 中添加壹個新字段。  但是,它仍然會返回壹篇文章。 在第二個選項中,URI 仍然很簡單,消費者不需要在客戶端實現中更改其 URI。

在消費者不提供版本號的情況下設計策略非常重要。 未提供版本時可能會引發錯誤,或者妳可以使用第壹個版本返回響應。  如果妳使用最新的穩定版本作為默認版本,則消費者可以為其客戶端實現獲取許多錯誤。

表示

表示是 API 顯示資源的方式。 當妳調用 API 端點時,妳將返回壹個資源。 此資源可以是 XML,JSON 等任何格式。如果妳正在設計新 API,則 JSON 更可取。  但是,如果要更新用於返回 XML 響應的現有 API,則可以為 JSON 響應提供另壹個版本。

這是關於 RESTful API 設計的足夠的理論信息。 讓我們通過使用 Restify 設計和實現 Blogging API 來了解實際使用情況。

博客 REST API

設計

為了設計 RESTful API,我們需要分析業務領域。 然後我們可以定義我們的資源。 在 Blogging API 中,我們需要:

  • 創建,更新,刪除,查看文章
  • 為特定文章,更新,刪除,查看,評論創建評論
  • 創建,更新,刪除,查看用戶

在此 API 中,我將不介紹如何對用戶進行身份驗證以創建文章或評論。 對於身份驗證部分,妳可以參考使用 AngularJS 和 NodeJS 的基於令牌的身份驗證教程。

我們的資源名稱已準備就緒 資源操作只是 CRUD。 妳可以參考下表了解 API 的壹般展示。

資源名稱 HTTP 動詞 HTTP 方法
刪除文章 創造文章
更新文章
刪除文章
查看文章
DELETE / articles / 123
DELETE / articles / 123
DELETE / articles / 123
GET / article / 123
創建評論 創建評論
更新評論
刪除評論
查看評論
有效負載的 POST / articles / 123 / 評論
帶有效負載的 PUT / comments / 123
DELETE / comments / 123
GET / comments / 123
用戶 創建用戶
更新用戶
刪除用戶
查看用戶
有效負載的 POST / 用戶
帶有效負載的 PUT / users / 123
DELETE / users / 123
GET / users / 123

項目設置

在這個項目中,我們將使用的 NodeJS 用的 RESTify。 資源將保存在 MongoDB 數據庫中。 首先,我們可以將資源定義為 Restify 中的模型。

文章

評論

用戶

用戶資源不會有任何操作。 我們假設我們已經知道能夠操作文章或評論的當前用戶。

妳可能會問這個模塊來自哪裏。 它是作為 NodeJS 模塊編寫的 MongoDB 最流行的 ORM 框架。 該模塊包含在另壹個配置文件中的項目中。

現在我們可以為上述資源定義 HTTP 動詞。 妳可以看到以下內容:

在此代碼段中,首先叠代包含控制器方法的所有控制器文件,並初始化所有控制器以執行對 URI 的特定請求。  之後,為基本 CRUD 操作定義特定操作的 URI。 還有壹篇關於文章操作的版本控制。

例如,如果在 Accept-Version 標頭中將版本聲明為 2,則將執行 viewArticle_v2。 viewArticle 和 viewArticle_v2 都執行相同的工作,顯示資源,但它們以不同的格式顯示文章資源,妳可以在下面的標題字段中看到。 最後,服務器在特定端口上啟動,並應用壹些錯誤報告檢查。 我們可以繼續使用控制器方法對資源進行 HTTP 操作。

article.js

妳可以在下面的 Mongoose 側找到有關基本 CRUD 操作的說明:

  • createArticle:這是對請求正文發送的 articleModel 的簡單保存操作。 可以通過將請求主體作為構造函數傳遞給 var articleModel = new Article(req.body)之類的模型來創建新模型。
  • viewArticle:為了查看文章詳細信息,URL 參數中需要壹個文章 ID。 帶有 ID 參數的 findOne 足以返回文章詳細信息。
  • updateArticle:文章更新是壹個簡單的查找查詢和對返回文章的壹些數據操作。 最後,需要通過發出 save 命令將更新的模型保存到數據庫中。
  • deleteArticle:findByIdAndRemove 是通過提供文章 ID 刪除文章的最適合方法了。

上面提到的 Mongoose 命令只是靜態的,就像通過 Article 對象的方法壹樣,它也是 Mongoose 模式的引用。

comment.js

當妳向其中壹個資源 URI 發出請求時,將執行控制器中聲明的相關功能。 控制器文件中的每個函數都可以使用 req 和 res 對象。 這裏的評論資源是文章的子資源。 所有查詢操作都是通過 Article 模型進行的,以便查找子文檔並進行必要的更新。 但是,每當妳嘗試查看 Comment 資源時,即使 MongoDB 中沒有集合,妳也會看到壹個。

其他設計建議

  • 選擇易於理解的資源,以便於消費者使用。
  • 讓業務邏輯由消費者實現。 例如,Article 資源有壹個名為 slug 的字段。 消費者無需將此詳細信息發送到 REST API。 這個 slug 策略應該在 REST API 端進行管理,以減少 API 和消費者之間的藕合。 消費者只需要發送標題詳細信息,妳可以根據 REST API 端的業務需求生成 slug。
  • 為 API 端點實施授權層。 未經授權的消費者可以訪問屬於另壹個用戶的受限數據。 在本教程中,我們沒有介紹用戶資源,但妳可以參考使用 AngularJS 和 NodeJS 的基於令牌的身份驗證,以獲取有關 API 身份驗證的更多信息。
  • 用戶 URI 而不是查詢字符串。/ articles / 123(好),/ articles?id = 123(差)。
  • 不要保持國家; 始終使用即時輸入 / 輸出。
  • 使用名詞作為資源。 妳可以使用 HTTP 方法來操作資源。

最後,如果妳按照這些基本規則設計 RESTful API,妳將始終擁有靈活,可維護,易於理解的系統。

Envato qr branded
关注我们的公众号
Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.