第 3 篇:實現博客首頁文章列表 API

hellogithub 發佈 2020-05-01T21:09:45+00:00

給api_view 裝飾器傳入 http_method_names 參數指定允許訪問該 API 視圖的 HTTP 方法。

作者:HelloGitHub-追夢人物

此前在討論基於模板引擎的開發方式和 django-rest-framework 開發的異同時說過,django-rest-framework 開發和傳統的開發方式沒有什麼不同,區別僅在於返回的數據格式不同而已。

在基於模板引擎的開發方式中,博客首頁文章列表的視圖函數可能是這樣的:

在 django-rest-framework,代碼邏輯是一樣的,只是在最後返回結果時,返回資源序列化後的結果。

暫且忽略掉資源序列化器 PostListSerializer,我們接下來會實現它,先把注意力放在主體邏輯上。

首先,我們從 rest_framework.decorators 中導入了 api_view 裝飾器,並用它裝飾了 index 視圖函數,使其成為一個 RESTful API 視圖函數。

為什麼需要這個視圖函數裝飾器呢?之前說過,django-rest-framework 為 API 的開發提供了豐富的功能,包括內容協商、認證和鑒權、限流等等。這些過程 django 默認的視圖函數在處理 HTTP 請求時是沒有提供的,而經過 api_view 裝飾後的視圖,則提供了上述全部功能。

不過我們這裡並沒有看到任何內容協商、認證和鑒權、限流代碼邏輯和配置,這是為什麼呢?原因隱藏在 Python 的裝飾器魔法裡,django-rest-framework 對於上述功能有一套默認的處理邏輯,因此我們不需要進行任何配置,僅需使用 api_view 裝飾一個 django 視圖函數,所有功能全部自動開啟。

視圖函數裡我們先從資料庫獲取文章列表資源,然後使用序列化器對其進行序列化,序列化後的數據存在 data 屬性里,我們把它傳遞給 HTTP 響應類 Response,並將這個響應返回。

注意這個 Response 是從 rest_framework.response 中導入的,它類似於 django 的 HTTPResponse 響應類。實際上,這個類是 django-rest-framework 對 django 的模板響應類(SimpleTemplateResponse)的拓展(具體的細節可以不用了解,只要知道 django 使用它來渲染模板並構造 HTTP 響應即可),通常在 RESTful API 的視圖函數中我們都會返回這個類,而不是 django 的 HTTP 響應類。此外,通過傳入 status 參數,指定 HTTP 響應的狀態碼。

小貼士

請了解常用的 HTTP 狀態碼。在 RESTful 架構中,客戶端通過 HTTP 請求動詞表征對資源的操作意圖,而服務端則使用 HTTP 狀態碼錶示資源操作的結果。常用狀態碼及其含義如下:

200:通常表示請求成功。

201:表示資源創建成功。

400:表示客戶端請求錯誤。

401:沒有提供身份認證信息

403:沒有操作權限

404 :訪問的資源不存在

405:不支持的 HTTP 請求方法

500:伺服器內部錯誤

HTTP 請求和響應過程,django-rest-framework 已經幫我們處理。但是資源的序列化,框架是無法自動化完成的,框架提供了基本的序列化器,我們需要自定義序列化邏輯。所以,讓我們來定義 PostListSerializer 序列化器,用它來序列化文章列表。

序列化器由一系列的序列化欄位(Field)組成,序列化欄位的作用是,在序列化資源時,將 Python 數據類型轉為原始數據類型(通常為字符類型或者二進位類型),以便在客戶端和服務端之間傳遞;反序列化時,將原始數據類型轉為 Python 數據類型。在轉換過程中,還會進行數據合法性的校驗。

先來看一個簡單的例子(摘自 django-rest-framework 官網示例),理解序列化器的工作原理和功能。假設我們有一個 Python 類 Comment:

根據 Comment 類 3 個屬性的類型,定義一個序列化器,用於數據序列化和反序列化。我們在上一步教程的 交流的橋樑:評論功能 中介紹過表單(Form)的定義。實際上,django-rest-framework 序列化器的設計參考了 django 表單的設計。序列化器和表單也有很多相似功能,比如對輸入數據進行校驗等。序列化器的代碼如下:

自定義的序列化器都要繼承 serializers.Serializer 基類,基類提供了數據序列化和反序列化的邏輯。根據被序列化對象的屬性的數據類型,需要指定相應的序列化欄位(Serializer Field)。django-rest-framework 提供了很多常用的序列化欄位,例如本例中用於序列化 email 數據格式的 EmailField,用於序列化字符型數據格式的 CharField,用於序列化日期格式的 DateTimeField。在實際項目中,應該根據數據類型,選擇合適的序列化欄位。全部序列化欄位,可以參考官方文檔 Serializer fields。

有了序列化器,就可以將 Comment 對象序列化了,序列化器用法如下:

首先將需要序列化的對象(comment)傳入序列化器(CommentSerializer),構造一個序列化器對象(serializer),訪問序列化器對象的 data 屬性,就可以得到序列化後的數據。

被序列化對象序列化後的數據是一個扁平的 Python 字典,字典中的數據描述了這個對象資源。有了序列化生成的 Python 字典,我們就可以將字典數據進一步格式化為 JSON 字符串或者 XML 文檔字符串,在客戶端和服務端之間傳輸。試想,客戶端服務端通常都通過 HTTP 協議傳輸數據,傳輸的數據只能是字符串或者二進位數據,不可能將一個 Python 的對象直接傳遞,這就是為什麼要序列化的原因。一端接收到序列化的數據後,如果有需要,可以對數據進行反序列化,重新恢復為 Python 對象。

以上就是一個標準序列化器的定義。其關鍵點在於,根據被序列化對象屬性的數據類型,選擇合適的序列化欄位。回顧我們在上一步教程的 交流的橋樑:評論功能 中對評論表單的定義,我們通過繼承 ModelForm 定義了表單,而並沒有顯示地指定表單欄位的類型。原因在於,對於 django 中的模型(Model),已經有了定義其數據類型的模型欄位,因此 django 表單可以根據關聯的模型,自動推測需要使用的表單欄位,在背後幫我們完成表單欄位的選擇,簡化了表單的定義。

和表單類似,django-rest-framework 的序列化器也可以根據關聯的模型,自動檢測被序列化模型各個屬性的數據類型,推測需要使用的序列化欄位,無需我們顯示定義。此時,自定義的序列化器不再繼承標準的 Serializer,而是繼承其子類,ModelSerializer。

我們來編寫文章(Post)模型的序列化器代碼。按照習慣,序列化器的代碼位於相應應用的 serializers.py 模塊中,因此在 blog 應用下新建一個 serializers.py 文件,寫上如下代碼:

使用 ModelSerializer 時,只需要在序列化器的內部類 Meta 中指定關聯的模型,以及需要序列化的模型屬性,django-rest-framework 就會根據各個屬性的數據類型,自動推測需要使用的系列化欄位,從而生成標準的序列化器。事實上,我們可以來看一下 django-rest-framework 最終生成的序列化器長什麼樣子:

還需要注意一點,title、created_time、views 這些屬性都是原始的數據類型(字符型、日期型、整數類型)。而對於文章關聯的 category、author,它們本身也是一個對象,django-rest-framework 就無法推測該使用什麼類型的系列化欄位來序列化它們了。所以這裡我們按照標準序列化器的定義方式,將這兩個屬性的系列化欄位分別定義為 CategorySerializer、UserSerializer,意思是告訴 django-rest-framework,請使用 CategorySerializer 和 UserSerializer 來序列化關聯的 category 和 author。實際上,序列化器本身也是一個序列化欄位。當然,CategorySerializer 和 UserSerializer 目前還不存在,我們來定義他們:

再來回顧一下我們的 API 視圖函數代碼:

注意這裡 PostListSerializer 的用法,構造序列化器時可以傳入單個對象,序列化器會將其序列化為一個字典;也可以傳入包含多個對象的可疊代類型(這裡的 post_list 是一個 django 的 QuerySet),此時需要設置 many 參數為 True 序列化器會依次序列化每一項,返回一個列表。

給 api_view 裝飾器傳入 http_method_names 參數指定允許訪問該 API 視圖的 HTTP 方法。

現在我們已經有了視圖函數,最後,我們需要給這個視圖函數綁定 URL,在 blog 應用下的 urls.py 中加入綁定的代碼:

path('api/index/', views.index)

啟動開發伺服器,打開瀏覽器訪問 http://127.0.0.1:8000/api/index/ ,可以看到接口返回了文章列表 JSON 格式的數據(默認為 JSON)。

目前來說,這個接口其實作用不大。不過在後續的教程中,我們學習前端框架 Vue,那個時候,RESTful API 就有了它的用武之地了。

回顧一下 index API 視圖函數的基本邏輯:

  1. 從資料庫取數據
  2. 構造序列化器並將取出的數據序列化
  3. 返迴響應

這其實是訪問序列型的資源比較常見的邏輯,我們知道,django 專門為這種在 Web 開發中常用的邏輯提供了一系列基於類的通用視圖,以提高代碼的復用性和減少代碼量。只是 django 的通用視圖適用於基於模板引擎的開發方式,同樣的,django-rest-framework 也提供了專門針對 RESTful API 開發過程中常用邏輯的類視圖通用函數。接下來,讓我們使用 django-rest-framework 提供的通用類視圖,將首頁 API 的視圖函數改為類視圖。

『講解開源項目系列』——讓對開源項目感興趣的人不再畏懼、讓開源項目的發起者不再孤單。跟著我們的文章,你會發現編程的樂趣、使用和發現參與開源項目如此簡單。歡迎留言聯繫我們、加入我們,讓更多人愛上開源、貢獻開源~

關鍵字: