Rest Framework設計規範

雲崖先生發表於2020-10-23
RESTFramework

Rest Framework

　　 Rest Framework是前後端分離中用到的一種規範，它與框架本身無關，是一種軟體架構風格，全稱為Representational State Transfer。

　　 Rest Framework最顯著的特點就是將一切資料看作資源，同時對不同的請求方式做出不同的責任劃分。這種結構理念也被稱為面向資源架構。

前後端分離

　　 不同於前後端混合開發中的介面，API介面主要用於為頁面提供資料。隨著前後端分離概念的出現，如今這種設計模式已是大勢所趨，前後端進行分離開發互不影響，而前端請求為頁面進行填充資料的介面則統稱為API介面。

　　 以下是前後端分離與混合開發的差異：

　　 前後端不分離：展示的頁面由後端決定，頁面上的資料由模板渲染而來。

　

　　 前後端分離：後端只返回頁面需要的資料，不再承擔模板的渲染工作，前後端開發耦合度較低。

API設計

　　 對於後端的API介面設計，應該遵循RESTful AIP規範。

  • 　　 通訊協議上應該採用HTTPS協議，確保資料安全

  • 　　 API的域名應該具有一定的辨識度，如下url示例：

    https://api.example.com  # 以api開頭
https://example.org/api/  # 以api結束

  • 　　 API中應當放入版本號，如下示例：

    https://api.example.com/v1/
https://api.example.com/v2/

  • 　　 API請求路徑中只能含有名詞，不應該含有動詞。而且所用的名詞往往與資料庫的表格名對應，支援複數（極其重要），如下示例：

    https://api.example.com/v1/book # 代表全部的書籍
https://api.example.com/v1/get_all_book # 不應該使用動詞，這是錯誤的形式

  • 　　 由於API不含有動詞，所以我們可以根據不同的請求方式對處理邏輯進行劃分，如下所示：

    GET（SELECT）：從伺服器取出資源（一項或多項）。
POST（CREATE）：在伺服器新建一個資源。
PUT（UPDATE）：在伺服器更新資源（客戶端提供改變後的完整資源）。
PATCH（UPDATE）：在伺服器更新資源（客戶端提供改變的屬性）。
DELETE（DELETE）：從伺服器刪除資源。

    　　 下面是一些例子：

    GET /book：列出所有書籍
POST /book：新建一本書籍
GET /book/ID：獲取某個指定書籍的資訊
PUT /book/ID：更新某個指定書籍的資訊（提供該書籍的全部資訊）
PATCH /book/ID：更新某個指定書籍的資訊（提供該書籍的部分資訊）
DELETE /book/ID：刪除某本資料
GET /book/ID/details：列出某本書籍的詳細資訊
DELETE /zoos/ID/author/ID：刪除某本指定書籍中的指定作者

  • 　　 如果記錄數量很多，伺服器不可能都將它們返回給使用者。API應該提供引數，過濾返回結果。

    　　 下面是一些常見的引數。

    ?limit=10：指定返回記錄的數量
?offset=10：指定返回記錄的開始位置。
?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
?animal_type_id=1：指定篩選條件

  • 　　 伺服器向使用者返回的狀態碼和提示資訊，常見的有以下一些（方括號中是該狀態碼對應的HTTP動詞）。

    200 OK - [GET]：伺服器成功返回使用者請求的資料，該操作是冪等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：使用者新建或修改資料成功。
202 Accepted - [*]：表示一個請求已經進入後臺排隊（非同步任務）
204 NO CONTENT - [DELETE]：使用者刪除資料成功。

400 INVALID REQUEST - [POST/PUT/PATCH]：使用者發出的請求有錯誤，伺服器沒有進行新建或修改資料的操作，該操作是冪等的。
401 Unauthorized - [*]：表示使用者沒有許可權（令牌、使用者名稱、密碼錯誤）。
403 Forbidden - [*] 表示使用者得到授權（與401錯誤相對），但是訪問是被禁止的。
404 NOT FOUND - [*]：使用者發出的請求針對的是不存在的記錄，伺服器沒有進行操作，該操作是冪等的。
406 Not Acceptable - [GET]：使用者請求的格式不可得（比如使用者請求JSON格式，但是隻有XML格式）。
410 Gone -[GET]：使用者請求的資源被永久刪除，且不會再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 當建立一個物件時，發生一個驗證錯誤。

500 INTERNAL SERVER ERROR - [*]：伺服器發生錯誤，使用者將無法判斷髮出的請求是否成功。

  • 　　 對於API的返回內容來說，如果狀態碼是4xx，則應該在返回資訊中新增error及詳細的錯誤描述。

    {
    error: "Invalid API key"
}

  • 　　 對於API的返回結果來說，應該針對不同的請求操作，伺服器向使用者返回的結果需符合以下規範。

    GET /collection：返回資源物件的列表（陣列）
GET /collection/resource：返回單個資源物件
POST /collection：返回新生成的資源物件
PUT /collection/resource：返回完整的資源物件
PATCH /collection/resource：返回完整的資源物件
DELETE /collection/resource：返回一個空文件

  • 　　 可以在返回的資訊中新增連結，讓使用者知道及時不檢視文件，下一步也可以做什麼。

    {"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}

相關文章