Django Rest framework 之 版本

• RESTful 規范
• django rest framework 之 認證（一）
• django rest framework 之 權限（二）
• django rest framework 之 節流（三）
• django rest framework 之 版本（四）
• django rest framework 之 解析器（五）
• django rest framework 之 序列化（六）
• django rest framework 之 分頁（七）
• django rest framework 之 視圖（八）

一、前言

1、版本的重要性

在RESTful 規范中，有關版本的問題，用restful規范做開放接口的時候，用戶請求API，系統返回數據。但是難免在系統發展的過程中，不可避免的需要添加新的資源，或者修改現有資源。因此，改動升級必不可少，但是，作為平台開發者，應該知道：一旦你的API開放出去，有人開始用了，平台的任何改動都需要考慮對當前用戶的影響。因此，做開放平台，從第一個API的設計就需要開始API的版本控制策略問題，API的版本控制策略就像是開放平台和平台用戶之間的長期協議，其設計的好壞將直接決定用戶是否使用該平台，或者說用戶在使用之后是否會因為某次版本升級直接棄用該平台。

2、定義版本

怎么定義版本協議，前端后端怎么協調。有以下幾種方式：

• 請求頭中定義

    GET /something/ HTTP/1.1
    Host: example.com
    Accept: application/json; version=1.0  #版本為1.0

• URL中定義

    URL: example.com/v1.0/  # 版本為1.0
    GET /1.0/something/ HTTP/1.1
    Host: example.com
    Accept: application/json

• 子域名中定義

    GET /something/ HTTP/1.1
    Host: v1.example.com # 版本為1.0
    Accept: application/json

• HttpReqeust參數傳遞

    GET /something/?version=0.1 HTTP/1.1  # 版本為1.0
    Host: example.com
    Accept: application/json

二、示例

在django rest framewrok中，如果沒有在配置文件setting.py中設置默認的VERSION_PARAM，即版本參數，drf會設置默認的參數為version，並將獲取到的version的值封裝到request.version中

1、請求頭中定義

django rest framework的request其實是對原生的Django的HttpRequest做了一個封裝，通過直接獲取屬性可以獲取到請求頭中的版本號
django rest framework的request

原生的Django的HttpRequest

請求頭的版本和其他請求頭信息最終會放到META中，因此想要獲取版本號可以如下這樣

version = request._request.META.get('version')  # 獲取版本號

2、子域名中定義

同樣的像請求頭中定義一樣，在請求頭中也可以直接獲取的域名，放到META中，因此想要獲取版本號可以如下這樣

host = request._request.META.get('HTTP_HOST')  # 先獲取主機域名
version = host.split('.')[0]  #  獲取版本號

注：其實在django rest framework內部也有關於以上兩種定義版本的處理方法

3、HttpReqeust參數傳遞

之前分別在django rest framework中關於節流，認證，權限三個組件，這里新建一個Django項目，命名為drf2。並進入當前目錄下執行python manage.py startapp api，將新建的app，和rest_framework放入INSTALLED_APPS。

# setting.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'api'
]

<1>、目錄結構

<2>、路由系統

from django.conf.urls import url

from .views import VersionView

urlpatterns = [
    url(r'^version/$', VersionView.as_view()),

]

<3>、視圖

from django.http import JsonResponse
from rest_framework.views import APIView
from rest_framework.versioning import  QueryParameterVersioning


class VersionView(APIView):
    versioning_class = QueryParameterVersioning  # 局部配置請求參數處理

    def get(self, request, *args, **kwargs):
        version = request.version
        ret = {
            'code': 1000,
            'msg': '請求成功',
            ‘version': version
        }
        return JsonResponse(ret)

<4>、配置文件

像之前在權限，節流那樣，可以配置一個全局默認的版本解析類

REST_FRAMEWORK = {
    "DEFAULT_VERSIONING_CLASS": "rest_framework.versioning.URLPathVersioning",  # 默認是url處理版本
    "DEFAULT_VERSION":'v1',  # 默認版本
    "ALLOWED_VERSIONS":['v1','v2'],  # 允許版本
    "VERSION_PARAM":'version',  # 版本參數例如  ?version=v1,，則表示版本為v1 
}

<5>、測試

使用postman或者瀏覽器發送請求測試

提供正常版本號：http://127.0.0.1:8000/api/version/?version=v1 獲取版本成功

發送錯誤版本號：http://127.0.0.1:8000/api/version/?version=v3 由於允許版本只有v1和v2，所以版本錯誤，返回錯誤信息

不提供版本號：假如在url請求中不添加參數，http://127.0.0.1:8000/api/version/?，能獲取到默認的版本號

4、URL中定義

在url中定義，例如http://127.0.0.1:8000/api/v1/

<1>、路由系統

from django.conf.urls import url

from .views import VersionView

urlpatterns = [
    url(r'^(?P<version>[v1|v2]+)/$', VersionView.as_view()),  # 可用版本為v1和v2
]

<2>、視圖

from django.http import JsonResponse
from django.http import HttpRequest
from rest_framework.views import APIView, Request
from rest_framework.versioning import URLPathVersioning


class VersionView(APIView):
    versioning_class = URLPathVersioning  # 局部配置版本類
    
    def get(self, request, *args, **kwargs):
        version = request.version
        ret = {
            'code': 1000,
            'msg': '請求成功',
            'version': version
        }
        return JsonResponse(ret)

或者也可以全局配置， 不過使用URL解析的時候，需要在路由系統中正則匹配設置可用的版本，

REST_FRAMEWORK = {
    "DEFAULT_VERSIONING_CLASS": "rest_framework.versioning.URLPathVersioning",
    "VERSION_PARAM":'version',  # 參數
}

<3>、測試

使用postman或者瀏覽器發送請求測試
http://127.0.0.1:8000/api/v1/，正確的獲取版本號

5、反向解析URL

在django中也提供了一個url解析的函數reverse，不過在django rest framework中也有一個將reverse函數封裝一層的接口可以進行url反向解析。

路由系統：加入namespace參數

from django.contrib import admin
from django.urls import path, include
from django.conf.urls import url

urlpatterns = [
    url(r'^api/', include('api.urls', namespace='api') ),
]

子路由系統：加入name參數

from django.conf.urls import url

from .views import VersionView

app_name = 'api' 

urlpatterns = [
    url(r'^version/$', VersionView.as_view(), name='version'),
    url(r'^(?P<version>[v1|v2]+)/$', VersionView.as_view(), name='version'),
]

示例一：參數攜帶版本

http://127.0.0.1:8000/api/version/?version=v1，發送請求

class VersionView(APIView):
    versioning_class = QueryParameterVersioning
    
    def get(self, request, *args, **kwargs):

        version = request.version
        url1 = request.versioning_scheme.reverse(viewname='api:version', request=request)

        url2 = reverse(viewname='api:version', kwargs=kwargs) 

        ret = {
            'code': 1000,
            'msg': '請求成功',
            'version': version,
            'drf_url': url1,
            'django_url': url2
        }
        return JsonResponse(ret)

使用postman返送請求

示例二：URL攜帶版本

http://127.0.0.1:8000/api/v1/，發送請求

class VersionView(APIView):
    versioning_class = URLPathVersioning

    def get(self, request, *args, **kwargs):

        version = request.version
        url1 = request.versioning_scheme.reverse(viewname='api:version', request=request)

        url2 = reverse(viewname='api:version', kwargs=kwargs)

        ret = {
            'code': 1000,
            'msg': '請求成功',
            'version': version,
            'drf_url': url1,
            'django_url': url2
        }
        return JsonResponse(ret)

使用postman返送請求

這里有與drf的reverse在對django中的reverse函數進行封裝的時候，獲取了request.get_full_url()，並做了一個拼接，所以才會出現全部的url

三、源碼分析

1、找到initial()方法

依舊從dispath方法進入源碼，找到initial方法

2、進入initial()方法

這里調用了determine_version()方法，並拿到兩個返回值並封裝到request中。這時候request.version_scheme就是一個版本對象了

3、查看具體的determine_version()方法

4、默認的版本處理對象

可以在setting.py中配置之后，全局使用

5、drf提供的版本類

在url反向解析中，調用了request.versioning_scheme.reverse()中的reverse()方法，說明request.versioning_scheme返回的是一個版本對象，可以調用他的方法

BaseVersioning基類定義了三個接口

• determine_version：返回版本
• reverse：url反向解析使用
• is_allowed_version：就是判斷版本號是否合法

而上面示例使用的兩個超類URLPathVersioning，QueryParameterVersioning其實也就是，重寫了determine_version，和reverse兩個方法。

四、總結

版本的獲取方式有多種，在django rest framewok中也提供了一一對應的處理版本對象，可以根據自己的需要配置，或者繼承重寫接口使用。
配置也支持全局配置，和局部配置，在全局配置的時候，需要定義默認的版本號，以防萬一。
在進行url反向解析的時候django rest framewok提供了一個更好的方式。