背景 項目當中需要進行業務時間的校驗,如上午 9:00-下午 17:00,在 9:00 前或 17:00 後是不能處理相關業務的。因此在業務校驗的 Service 中定義了一個 checkBizTime() 方法。原本代碼如下: public void checkBizTime() { Date c ...
本文從分析現在流行的前後端分離Web應用模式說起,然後介紹如何設計REST API,通過使用Django來實現一個REST API為例,明確後端開發REST API要做的最核心工作,然後介紹Django REST framework能幫助我們簡化開發REST API的工作。
Web應用模式
在開發Web應用中,有兩種應用模式:
前後端不分離
前後端分離
1 前後端不分離
在前後端不分離的應用模式中,前端頁面看到的效果都是由後端控制,由後端渲染頁面或重定向,也就是後端需要控制前端的展示,前端與後端的耦合度很高。
這種應用模式比較適合純網頁應用,但是當後端對接App時,App可能並不需要後端返回一個HTML網頁,而僅僅是數據本身,所以後端原本返回網頁的介面不再適用於前端App應用,為了對接App後端還需再開發一套介面。
HTTP動詞
對於資源的具體操作類型,由HTTP動詞表示。
常用的HTTP動詞有下麵四個(括弧里是對應的SQL命令)。
- GET(SELECT):從伺服器取出資源(一項或多項)。
- POST(CREATE):在伺服器新建一個資源。
- PUT(UPDATE):在伺服器更新資源(客戶端提供改變後的完整資源)。
- DELETE(DELETE):從伺服器刪除資源。
還有三個不常用的HTTP動詞。
- PATCH(UPDATE):在伺服器更新(更新)資源(客戶端提供改變的屬性)。
- HEAD:資源的元數據。
- OPTIONS:信息,關於資源的哪些屬性是客戶端可以改變的。
下麵是一些例子。
過濾信息(Filtering)
如果記錄數量很多,伺服器不可能都將它們返回給用戶。API應該提供參數,過濾返回結果。
下麵是一些常見的參數。
?limit=10:指定返回記錄的數量
?offset=10:指定返回記錄的開始位置。
?page=2&per_page=100:指定第幾頁,以及每頁的記錄數。
?sortby=name&order=asc:指定返回結果按照哪個屬性排序,以及排序順序。
?animal_type_id=1:指定篩選條件
參數的設計允許存在冗餘,即允許API路徑和URL參數偶爾有重覆。比如,GET /zoos/ID/animals 與 GET
/animals?zoo_id=ID 的含義是相同的。
狀態碼(Status Codes)
伺服器向用戶返回的狀態碼和提示信息,常見的有以下一些(方括弧中是該狀態碼對應的HTTP動詞)。
- 200 OK - [GET]:伺服器成功返回用戶請求的數據
- 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 - [*]:伺服器發生錯誤,用戶將無法判斷發出的請求是否成功。
期待下期