架構之: REST 中的資源定義

簡介

我們知道 REST 架構中資源是非常重要的，REST 的一切都是圍繞資源來定義的，那麼資源是什麼，怎麼命名資源和對其定義呢？一起來看看吧。

資源

資源是什麼呢？資源是 REST 中信息的關鍵抽象。在 REST 中任何可以被命名的信息都可以被稱爲資源。比如：實體、對象、文檔、圖像、實體集合、服務等。

資源是和狀態相關的，任何一個特定時間點的資源都有屬於自己的資源狀態。這些狀態是由數據、描述數據的元數據和超媒體鏈接組成。

怎麼理解這個超鏈接呢？這個超鏈接指向的是資源相關的 URI。

資源的請求方法

定義好了資源，我們還需要定義資源的請求方法。

很多人認爲，REST 的資源請求方法是不是就是 HTTP GET/PUT/POST/DELETE ？事實上 Roy Fielding 在論文中從未提起應該在哪種情況下使用哪種方法。他所強調的只是它應該是統一的接口。

只要是統一的方法即可。

很多人喜歡將 HTTP 與 REST 進行比較。但是 REST 和 HTTP 不一樣。在 REST 架構風格中，數據和功能被視爲資源，並使用統一資源標識符 (URI) 進行訪問。通過使用一組簡單的、定義良好的操作來處理資源。客戶端和服務器通過使用標準化的接口和協議（通常是 HTTP）來交換資源。

資源是與表現形式進行分離的，以便可以以各種格式訪問其內容，例如 HTML、XML、純文本、PDF、JPEG、JSON 等。

只不過因爲 REST 更多的被應用在 web 程序中，所以 HTTP 只能算是 REST 的一種實現方式。他們是不等同的。

REST 資源命名規則

在 REST 中，資源就是一切，所以對資源進行良好的命名是非常有必要的。

在 REST 中，任何可以被命名的信息都可以被稱爲資源，資源可以是單體也可以是集合，比如 students 是一個集合，表示很多學生，而一個 student 表示的是一個學生的個體。

那麼我們可以使用/students來表示學生的集合資源，然後用/students/{studentID}來表示特定的某個學生。

單個資源也可能包含子集合，比如一個 student 可能有很多個課程，我們用 courses 來表示，那麼其對應的 URI 就是：/students/{studentID}/courses。

REST API 使用 URI 來進行資源的定位，所以這個 URI 需要直觀並且容易使用。

資源命名最佳實踐

接下來，我們會講解一下 REST 中資源的命名最佳實踐。

使用名詞來定義資源

資源本身就是一個名詞，所以我們需要儘可能的用名詞來定義資源，對資源的操作可以通過不同的方法來表示。

像我們之前定義的學生相關的資源：

/students
/students/{studentID}
/students/{studentID}/courses

事實上基本上所有的資源都可以被分爲 4 類，分別是文檔、集合、存儲和控制器（document, collection, store and controller），我們在定義資源的是，需要儘可能的將其歸類，然後使用對應的命名規則。

文檔是一個類似於單一的對象實例或數據庫記錄的概念。在 REST 中，您可以將其視爲資源集合中的單個資源。

文檔通常用單數來表示：

/managed-devices/{device-id}
/users/{id}
/users/admin

集合很好理解，就是服務器管理的資源目錄，它裏面可以包含很多個資源，客戶端可能會希望向集合中插入新的資源，但是是否能夠插入是由服務器端來控制的。

集合通常用複數來表示。

/managed-devices
/users
/users/{id}/accounts

存儲是客戶端管理的資源庫，對於該資源庫的增刪改查是由 API 客戶端根據不同的調用方式來決定的。

存儲通常用複數來表示。

/users/{id}/playlists

控制器表示的是一個過程。控制器資源就像可執行函數，有參數和返回值，輸入和輸出。

控制器通常用動詞來表示。

/users/{id}/cart/checkout
/users/{id}/playlist/play

使用一致的命名規則

使用一致的資源命名約定和 URI 格式，以最大限度地減少歧義和最大的可讀性和可維護性。

我們可以歸納爲下面幾點：

  1. 使用/來表示資源的層級關係，如：
/managed-devices
  1. 不要在資源的最後加上/，如：
/managed-devices/
  1. 如果名稱太長，可以加上 (-) 提高可讀性：
/managed-entities/{id}/install-script-location

  1. 不要使用下劃線，如果要用，請使用 (-) 。

  2. 使用小寫字母，增加可讀性。

  3. 不要添加文件後綴，如 managed-devices.xml 直接用 managed-devices 表示即可。

不要在資源名字中使用 CURD

CRUD 應該由請求資源的方法來區分，不要直接在資源命名上帶上 CURD。

比如我想獲取 students 的信息，那麼定義的資源是 / students 而不是 / get-students。

使用下面的請求方式，表示是 get 請求即可：

HTTP GET /students

使用查詢組件過濾 URI 集合

很多時候，您會遇到需要根據某些特定資源屬性對資源進行排序、過濾或限制的集合的需求。在這種情況下，不要創建新的 API, 而是在資源集合 API 中啓用排序、過濾和分頁功能，並將輸入參數作爲查詢參數傳遞。例如:

/managed-devices?region=USA
/managed-devices?region=USA&brand=XYZ

總結

以上內容就是今天要講的 REST 資源命名規則，後面我們會介紹一個 REST 架構的更加嚴格的限制規則 HATEOAS。

本文已收錄於 http://www.flydean.com/02-rest-resource/

最通俗的解讀，最深刻的乾貨，最簡潔的教程，衆多你不知道的小技巧等你來發現！

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/vAc83ca7t3Qo3_6zAWeaiw

猜你喜歡