django rest framework drf 知識點大集合共5大子產品（第一期）

整個部落格系列：

Web應用前後端分離結構
Web API接口設計的RESTful風格
Django REST framework架構

完整筆記自取：

完整筆記直接在這自取

筆記分享dizhi

本期講解正式開始

引入Django REST framework

在本章中，我們要大家介紹為什麼學習Django REST framework，它能幫助我們做哪些事情。

課程思路：

我們從分析現在流行的前後端分離Web應用模式說起，然後介紹如何設計REST API，通過使用Django來實作一個REST API為例，明确後端開發REST

API要做的最核心工作，然後介紹Django REST framework能幫助我們簡化開發REST API的工作。

Web應用模式

在開發Web應用中，有兩種應用模式：

前後端不分離
前後端分離

1 前後端不分離

在前後端不分離的應用模式中，前端頁面看到的效果都是由後端控制，由後端渲染頁面或重定向，也就是後端需要控制前端的展示，前端與後端的耦合度很高。

這種應用模式比較适合純網頁應用，但是當後端對接App時，App可能并不需要後端傳回一個HTML網頁，而僅僅是資料本身，是以後端原本傳回網頁的接口不再适用于前端App應用，為了對接App後端還需再開發一套接口。

2 前後端分離

在前後端分離的應用模式中，後端僅傳回前端所需的資料，不再渲染HTML頁面，不再控制前端的效果。至于前端使用者看到什麼效果，從後端請求的資料如何加載到前端中，都由前端自己決定，網頁有網頁的處理方式，App有App的處理方式，但無論哪種前端，所需的資料基本相同，後端僅需開發一套邏輯對外提供資料即可。

在前後端分離的應用模式中，前端與後端的耦合度相對較低。

在前後端分離的應用模式中，我們通常将後端開發的每個視圖都稱為一個接口，或者 API ，前端通過通路接口來對資料進行增删改查。

____

認識RESTful

在前後端分離的應用模式裡，後端API接口如何定義？

例如對于後端資料庫中儲存了商品的資訊，前端可能需要對商品資料進行增删改查，那相應的每個操作後端都需要提供一個API接口：

1. POST /add-goods 增加商品
2. POST /delete-goods 删除商品
3. POST /update-goods 修改商品
4. GET /get-goods 查詢商品資訊

對于接口的請求方式與路徑，每個後端開發人員可能都有自己的定義方式，風格迥異。

是否存在一種統一的定義方式，被廣大開發人員接受認可的方式呢？

這就是被普遍采用的API的RESTful設計風格。

RESTful設計方法

1\. 域名

應該盡量将API部署在專用域名之下。

https://api.example.com

如果确定API很簡單，不會有進一步擴充，可以考慮放在主域名下。

https://example.org/api/

2\. 版本（Versioning）

應該将API的版本号放入URL。

http://www.example.com/api/1.0/foo

http://www.example.com/api/1.1/foo

http://www.example.com/ap、/2.0/foo

另一種做法是，将版本号放在HTTP頭資訊中，但不如放入URL友善和直覺。[Github](https://developer.github.com/v3/media/#request-

specific-version)采用這種做法。

因為不同的版本，可以了解成同一種資源的不同表現形式，是以應該采用同一個URL。版本号可以在HTTP請求頭資訊的Accept字段中進行區分（參見Versioning

REST Services）：

Accept: vnd.example-com.foo+json; version=1.0

Accept: vnd.example-com.foo+json; version=1.1

Accept: vnd.example-com.foo+json; version=2.0

3\. 路徑（Endpoint）

路徑又稱"終點"（endpoint），表示API的具體網址，每個網址代表一種資源（resource）

(1) 資源作為網址，隻能有名詞，不能有動詞，而且所用的名詞往往與資料庫的表名對應。

舉例來說，以下是不好的例子:

/getProducts
/listOrders
/retreiveClientByOrder?orderId=1

對于一個簡潔結構，你應該始終用名詞。此外，利用的HTTP方法可以分離網址中的資源名稱的操作。

GET /products ：将傳回所有産品清單
POST /products ：将産品建立到集合
GET /products/4 ：将擷取産品 4
PATCH（或）PUT /products/4 ：将更新産品 4

(2) API 中的名詞應該使用複數。無論子資源或者所有資源。

舉例來說，擷取産品的API可以這樣定義

擷取單個産品：http://127.0.0.1:8080/AppName/rest/products/1
擷取所有産品: http://127.0.0.1:8080/AppName/rest/products

3\. HTTP動詞

對于資源的具體操作類型，由HTTP動詞表示。

常用的HTTP動詞有下面四個（括号裡是對應的SQL指令）。

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

還有三個不常用的HTTP動詞。

PATCH（UPDATE）：在伺服器更新(更新)資源（用戶端提供改變的屬性）。
HEAD：擷取資源的中繼資料。
OPTIONS：擷取資訊，關于資源的哪些屬性是用戶端可以改變的。

下面是一些例子。

GET /zoos：列出所有動物園
POST /zoos：建立一個動物園（上傳檔案）
GET /zoos/ID：擷取某個指定動物園的資訊
PUT /zoos/ID：更新某個指定動物園的資訊（提供該動物園的全部資訊）
PATCH /zoos/ID：更新某個指定動物園的資訊（提供該動物園的部分資訊）
DELETE /zoos/ID：删除某個動物園
GET /zoos/ID/animals：列出某個指定動物園的所有動物
DELETE /zoos/ID/animals/ID：删除某個指定動物園的指定動物

4\. 過濾資訊（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 的含義是相同的。

6\. 狀态碼（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 - [*]：伺服器發生錯誤，使用者将無法判斷發出的請求是否成功。

狀态碼的完全清單參見這裡或這裡。

7\. 錯誤處理（Error handling）

如果狀态碼是4xx，伺服器就應該向使用者傳回出錯資訊。一般來說，傳回的資訊中将error作為鍵名，出錯資訊作為鍵值即可。

{
    error: "Invalid API key"
}

8\. 傳回結果

針對不同操作，伺服器向使用者傳回的結果應該符合以下規範。

GET /collection：傳回資源對象的清單（數組）
GET /collection/resource：傳回單個資源對象
POST /collection：傳回新生成的資源對象
PUT /collection/resource：傳回完整的資源對象
PATCH /collection/resource：傳回完整的資源對象
DELETE /collection/resource：傳回一個空文檔

9\. 超媒體（Hypermedia API）

RESTful API最好做到Hypermedia（即傳回結果中提供連結，連向其他API方法），使得使用者不查文檔，也知道下一步應該做什麼。

比如，Github的API就是這種設計，通路api.github.com會得到一個所有可用API的網址清單。

{
"current_user_url": "https://api.github.com/user",
"authorizations_url": "https://api.github.com/authorizations",
// ...
}

從上面可以看到，如果想擷取目前使用者的資訊，應該去通路api.github.com/user，然後就得到了下面結果。

{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}

django rest framework drf 知識點大集合共5大子產品（第一期）