DRF (Django REST framework) 框架介紹(1)

時間  2020-08-20
標籤 drf django rest framework 框架 介紹 欄目 Python 简体版
原文   原文鏈接

Web應用模式

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

  • 先後端不分離
  • 先後端分離

1 先後端不分離

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

這種應用模式比較適合純網頁應用，可是當後端對接App時，App可能並不須要後端返回一個HTML網頁，而僅僅是數據自己，因此後端本來返回網頁的接口再也不適用於前端App應用，爲了對接App後端還需再開發一套接口。前端

2 先後端分離

在先後端分離的應用模式中，後端僅返回前端所需的數據，再也不渲染HTML頁面，再也不控制前端的效果。至於前端用戶看到什麼效果，從後端請求的數據如何加載到前端中，都由前端本身決定，網頁有網頁的處理方式，App有App的處理方式，但不管哪一種前端，所需的數據基本相同，後端僅需開發一套邏輯對外提供數據便可。python

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

在先後端分離的應用模式中，咱們一般將後端開發的每一個視圖都稱爲一個接口，或者API，前端經過訪問接口來對數據進行增刪改查。github

認識RESTful

即Representational State Transfer的縮寫。維基百科稱其爲「具象狀態傳輸」，國內大部分人理解爲「表現層狀態轉化」。web

RESTful是一種開發理念。維基百科說：REST是設計風格而不是標準。 REST描述的是在網絡中client和server的一種交互形式；REST自己不實用，實用的是如何設計 RESTful API（REST風格的網絡接口）,一種萬維網軟件架構風格。數據庫

咱們先來具體看下RESTful風格的url,好比我要查詢商品信息，那麼django

非REST的url：http://.../queryGoods?id=1001&type=t01json

REST的url: http://.../t01/goods/1001

能夠看出REST特色：url簡潔，將參數經過url傳到服務器，而傳統的url比較囉嗦，並且現實中瀏覽器地址欄會拼接一大串字符，想必大家都見過吧。可是採用REST的風格就會好不少，如今不少的網站已經採用這種風格了，這也是潮流方向，典型的就是url的短化轉換。

那麼，到底什麼是RESTFul架構： 若是一個架構符合REST原則，就稱它爲RESTful架構。

要理解RESTful架構，理解Representational State Transfer這三個單詞的意思。

  • 具象的，就是指表現層，要表現的對象也就是「資源」，什麼是資源呢？網站就是資源共享的東西，客戶端（瀏覽器）訪問web服務器，所獲取的就叫資源。好比html，txt，json，圖片，視頻等等。

  • 表現，好比，文本能夠用txt格式表現，也能夠用HTML格式、XML格式、JSON格式表現，甚至能夠採用二進制格式；圖片能夠用JPG格式表現，也能夠用PNG格式表現。

    瀏覽器經過URL肯定一個資源，可是如何肯定它的具體表現形式呢？應該在HTTP請求的頭信息中用Accept和Content-Type字段指定，這兩個字段纔是對"表現層"的描述。

  • 狀態轉換， 就是客戶端和服務器互動的一個過程，在這個過程當中, 勢必涉及到數據和狀態的變化, 這種變化叫作狀態轉換。

    互聯網通訊協議HTTP協議，客戶端訪問必然使用HTTP協議，若是客戶端想要操做服務器，必須經過某種手段，讓服務器端發生"狀態轉化"（State Transfer）。

    HTTP協議實際上含有4個表示操做方式的動詞，分別是 GET,POST,PUT,DELETE,他們分別對應四種操做。GET用於獲取資源，POST用於新建資源，PUT用於更新資源，DElETE用於刪除資源。GET和POST是表單提交的兩種基本方式，比較常見，而PUT和DElETE不太經常使用。

    並且HTTP協議是一種無狀態協議，這樣就必須把全部的狀態都保存在服務器端。所以，若是客戶端想要操做服務器，必須經過某種手段，讓服務器端發生"狀態轉化"（State Transfer）

總結

綜合上面的解釋，RESTful架構就是：

  • 每個URL表明一種資源；
  • 客戶端和服務器之間，傳遞這種資源的某種表現層；
  • 客戶端經過四個HTTP動詞，對服務器端資源進行操做，實現"表現層狀態轉化"。

RESTful設計方法

1. 域名

應該儘可能將API部署在專用域名之下。

https://api.example.com

若是肯定API很簡單，不會有進一步擴展，能夠考慮放在主域名下。

https://example.org/api/

2. 版本（Versioning）

應該將API的版本號放入URL。

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

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

http://www.example.com/app/2.0/foo

另外一種作法是，將版本號放在HTTP頭信息中，但不如放入URL方便和直觀。Github採用這種作法。

由於不一樣的版本，能夠理解成同一種資源的不一樣表現形式，因此應該採用同一個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" }

上面代碼表示，服務器給出了提示信息，以及文檔的網址。

10. 其餘

服務器返回的數據格式，應該儘可能使用JSON，避免使用XML。

使用Django開發REST 接口
咱們以在Django框架中使用的圖書英雄案例來寫一套支持圖書數據增刪改查的REST API接口，來理解REST API的開發。

在此案例中，先後端均發送JSON格式數據。

# views.py

from datetime import datetime

class BooksAPIVIew(View):
    """
    查詢全部圖書、增長圖書
    """
    def get(self, request):
        """
        查詢全部圖書
        路由：GET /books/
        """
        queryset = BookInfo.objects.all()
        book_list = []
        for book in queryset:
            book_list.append({
                'id': book.id,
                'btitle': book.btitle,
                'bpub_date': book.bpub_date,
                'bread': book.bread,
                'bcomment': book.bcomment,
                'image': book.image.url if book.image else ''
            })
        return JsonResponse(book_list, safe=False)

    def post(self, request):
        """
        新增圖書
        路由：POST /books/ 
        """
        json_bytes = request.body
        json_str = json_bytes.decode()
        book_dict = json.loads(json_str)

        # 此處詳細的校驗參數省略

        book = BookInfo.objects.create(
            btitle=book_dict.get('btitle'),
            bpub_date=datetime.strptime(book_dict.get('bpub_date'), '%Y-%m-%d').date()
        )

        return JsonResponse({
            'id': book.id,
            'btitle': book.btitle,
            'bpub_date': book.bpub_date,
            'bread': book.bread,
            'bcomment': book.bcomment,
            'image': book.image.url if book.image else ''
        }, status=201)


class BookAPIView(View):
    def get(self, request, pk):
        """
        獲取單個圖書信息
        路由： GET  /books/<pk>/
        """
        try:
            book = BookInfo.objects.get(pk=pk)
        except BookInfo.DoesNotExist:
            return HttpResponse(status=404)

        return JsonResponse({
            'id': book.id,
            'btitle': book.btitle,
            'bpub_date': book.bpub_date,
            'bread': book.bread,
            'bcomment': book.bcomment,
            'image': book.image.url if book.image else ''
        })

    def put(self, request, pk):
        """
        修改圖書信息
        路由： PUT  /books/<pk>
        """
        try:
            book = BookInfo.objects.get(pk=pk)
        except BookInfo.DoesNotExist:
            return HttpResponse(status=404)

        json_bytes = request.body
        json_str = json_bytes.decode()
        book_dict = json.loads(json_str)

        # 此處詳細的校驗參數省略

        book.btitle = book_dict.get('btitle')
        book.bpub_date = datetime.strptime(book_dict.get('bpub_date'), '%Y-%m-%d').date()
        book.save()

        return JsonResponse({
            'id': book.id,
            'btitle': book.btitle,
            'bpub_date': book.bpub_date,
            'bread': book.bread,
            'bcomment': book.bcomment,
            'image': book.image.url if book.image else ''
        })

    def delete(self, request, pk):
        """
        刪除圖書
        路由： DELETE /books/<pk>/
        """
        try:
            book = BookInfo.objects.get(pk=pk)
        except BookInfo.DoesNotExist:
            return HttpResponse(status=404)

        book.delete()

        return HttpResponse(status=204)
# urls.py

urlpatterns = [
    url(r'^books/$', views.BooksAPIVIew.as_view()),
    url(r'^books/(?P<pk>\d+)/$', views.BookAPIView.as_view())
]
測試
使用Postman測試上述接口

1） 獲取全部圖書數據

GET 方式訪問 http://127.0.0.1:8000/books/， 返回狀態碼200，數據以下

[
    {
        "id": 1,
        "btitle": "射鵰英雄傳",
        "bpub_date": "1980-05-01",
        "bread": 12,
        "bcomment": 34,
        "image": ""
    },
    {
        "id": 2,
        "btitle": "天龍八部",
        "bpub_date": "1986-07-24",
        "bread": 36,
        "bcomment": 40,
        "image": ""
    },
    {
        "id": 3,
        "btitle": "笑傲江湖",
        "bpub_date": "1995-12-24",
        "bread": 20,
        "bcomment": 80,
        "image": ""
    },
    {
        "id": 4,
        "btitle": "雪山飛狐",
        "bpub_date": "1987-11-11",
        "bread": 58,
        "bcomment": 24,
        "image": ""
    },
    {
        "id": 5,
        "btitle": "西遊記",
        "bpub_date": "1988-01-01",
        "bread": 10,
        "bcomment": 10,
        "image": "booktest/xiyouji.png"
    },
    {
        "id": 6,
        "btitle": "水滸傳",
        "bpub_date": "1992-01-01",
        "bread": 10,
        "bcomment": 11,
        "image": ""
    },
    {
        "id": 7,
        "btitle": "紅樓夢",
        "bpub_date": "1990-01-01",
        "bread": 0,
        "bcomment": 0,
        "image": ""
    }
]
2）獲取單一圖書數據

GET 訪問 http://127.0.0.1:8000/books/5/ ，返回狀態碼200， 數據以下

{
    "id": 5,
    "btitle": "西遊記",
    "bpub_date": "1988-01-01",
    "bread": 10,
    "bcomment": 10,
    "image": "booktest/xiyouji.png"
}
GET 訪問http://127.0.0.1:8000/books/100/，返回狀態碼404

3）新增圖書數據

POST 訪問http://127.0.0.1:8000/books/，發送JSON數據：

{
    "btitle": "三國演義",
    "bpub_date": "1990-02-03"
}
返回狀態碼201，數據以下

{
    "id": 8,
    "btitle": "三國演義",
    "bpub_date": "1990-02-03",
    "bread": 0,
    "bcomment": 0,
    "image": ""
}
4）修改圖書數據

PUT 訪問http://127.0.0.1:8000/books/8/，發送JSON數據：

{
    "btitle": "三國演義（第二版）",
    "bpub_date": "1990-02-03"
}
返回狀態碼200，數據以下

{
    "id": 8,
    "btitle": "三國演義（第二版）",
    "bpub_date": "1990-02-03",
    "bread": 0,
    "bcomment": 0,
    "image": ""
}
5）刪除圖書數據

DELETE 訪問http://127.0.0.1:8000/books/8/，返回204狀態碼

明確REST接口開發的核心任務

分析一下上節的案例，能夠發現，在開發REST API接口時，視圖中作的最主要有三件事：

  • 將請求的數據（如JSON格式）轉換爲模型類對象
  • 操做數據庫
  • 將模型類對象轉換爲響應的數據（如JSON格式）

序列化Serialization

維基百科中對於序列化的定義：

序列化（serialization）在計算機科學的資料處理中，是指將數據結構或物件狀態轉換成可取用格式（例如存成檔案，存於緩衝，或經由網絡中傳送），以留待後續在相同或另外一臺計算機環境中，能恢復原先狀態的過程。依照序列化格式從新獲取字節的結果時，能夠利用它來產生與原始物件相同語義的副本。對於許多物件，像是使用大量參照的複雜物件，這種序列化重建的過程並不容易。面向對象中的物件序列化，並不歸納以前原始物件所關聯的函式。這種過程也稱爲物件編組（marshalling）。從一系列字節提取數據結構的反向操做，是反序列化（也稱爲解編組, deserialization, unmarshalling）。

序列化在計算機科學中一般有如下定義:

​ 在數據儲存與傳送的部分是指將一個對象)存儲至一個儲存媒介，例如檔案或是記億體緩衝等，或者透過網絡傳送資料時進行編碼的過程，能夠是字節或是XML等格式。而字節的或XML編碼格式能夠還原徹底相等的對象)。這程序被應用在不一樣應用程序之間傳送對象)，以及服務器將對象)儲存到檔案或數據庫。相反的過程又稱爲反序列化。

簡而言之，咱們能夠將序列化理解爲：

將程序中的一個數據結構類型轉換爲其餘格式（字典、JSON、XML等），例如將Django中的模型類對象裝換爲JSON字符串，這個轉換過程咱們稱爲序列化。

如：

queryset = BookInfo.objects.all()
book_list = []
# 序列化 for book in queryset: book_list.append({ 'id': book.id, 'btitle': book.btitle, 'bpub_date': book.bpub_date, 'bread': book.bread, 'bcomment': book.bcomment, 'image': book.image.url if book.image else '' }) return JsonResponse(book_list, safe=False)

反之，將其餘格式（字典、JSON、XML等）轉換爲程序中的數據，例如將JSON字符串轉換爲Django中的模型類對象，這個過程咱們稱爲反序列化。

如：

json_bytes = request.body
json_str = json_bytes.decode()

# 反序列化 book_dict = json.loads(json_str) book = BookInfo.objects.create( btitle=book_dict.get('btitle'), bpub_date=datetime.strptime(book_dict.get('bpub_date'), '%Y-%m-%d').date() )

咱們能夠看到，在開發REST API時，視圖中要頻繁的進行序列化與反序列化的編寫。

總結

在開發REST API接口時，咱們在視圖中須要作的最核心的事是：

  • 將數據庫數據序列化爲前端所須要的格式，並返回；

  • 將前端發送的數據反序列化爲模型類對象，並保存到數據庫中。

Django REST framework 簡介

  1. 在序列化與反序列化時，雖然操做的數據不盡相同，可是執行的過程倒是類似的，也就是說這部分代碼是能夠複用簡化編寫的。
  2. 在開發REST API的視圖中，雖然每一個視圖具體操做的數據不一樣，但增、刪、改、查的實現流程基本套路化，因此這部分代碼也是能夠複用簡化編寫的：
    • 增：校驗請求數據 -> 執行反序列化過程 -> 保存數據庫 -> 將保存的對象序列化並返回
    • 刪：判斷要刪除的數據是否存在 -> 執行數據庫刪除
    • 改：判斷要修改的數據是否存在 -> 校驗請求的數據 -> 執行反序列化過程 -> 保存數據庫 -> 將保存的對象序列化並返回
    • 查：查詢數據庫 -> 將數據序列化並返回

Django REST framework能夠幫助咱們簡化上述兩部分的代碼編寫，大大提升REST API的開發速度。

認識Django REST framework

drf_logo

Django REST framework 框架是一個用於構建Web API 的強大而又靈活的工具。

一般簡稱爲DRF框架 或 REST framework。

DRF框架是創建在Django框架基礎之上，由Tom Christie大牛二次開發的開源項目。

特色

  • 提供了定義序列化器Serializer的方法，能夠快速根據 Django ORM 或者其它庫自動序列化/反序列化；
  • 提供了豐富的類視圖、Mixin擴展類，簡化視圖的編寫；
  • 豐富的定製層級：函數視圖、類視圖、視圖集合到自動生成 API，知足各類須要；
  • 多種身份認證和權限認證方式的支持；
  • 內置了限流系統；
  • 直觀的 API web 界面；
  • 可擴展性，插件豐富

資料：

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程