淺析Django接口版本控制

一、前言

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

二、配置

有兩種配置方案,一種是在settings中全局配置,第二種是在視圖中指定,不過此方法一般不使用,因為版本控制大部分情況下是全局的處理情況

2.1、全局配置

settings.py

REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': None,
    'DEFAULT_VERSION': None,
    'ALLOWED_VERSIONS': None,
    'VERSION_PARAM': 'version',
}
  • DEFAULT_VERSIONING_CLASS:指定版本控制的類,譬如:’rest_framework.versioning.NamespaceVersioning’,有多種方式。默認為None,為None時,框架變量request.version將始終返回None
  • DEFAULT_VERSION:當版本控制信息不存在時用於設置request.version的默認值,默認設置為None。
  • ALLOWED_VERSIONS:允許的版本號,譬如:[‘v1’, ‘v2’]。區分大小寫,如果請求的版本號不在此列表中,拋出錯誤,上述的 DEFAULT_VERSION 的值必須是列表中的值,None除外
  • VERSION_PARAM:版本控制參數的字符串,默認就是version,一般不修改

2.2、視圖配置

views.py

# 僅僅指定 版本控制類    
class ProfileList(APIView):
    # 指定 版本控制類
    versioning_class = versioning.QueryParameterVersioning

三、drf內置的5個版本控制類

3.1、AcceptHeaderVersioning

基於請求頭的版本控制,這種方式也是最推薦的方式

3.1.1、http訪問方式

GET /bookings/ HTTP/1.1

Host: example.com

Accept: application/json; version=1.0

在上面的示例請求中request.version屬性將返回字符串’1.0’。 基於accept headers 的版本控制通常被認為是最佳實踐,盡管其他版本控制方式可能適合你的客戶端需求。

3.1.2、settings

REST_FRAMEWORK = {
	'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.AcceptHeaderVersioning',
        'DEFAULT_VERSION': 'v1',
        'ALLOWED_VERSIONS': ['v1', 'v2'],
}

說明:

  • 設置版本控制類為AcceptHeaderVersioning
  • 沒有檢測到version時,默認是v1版本
  • 允許的2個版本型號為:['v1', 'v2']

3.1.3、serializers

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = BookInfo
        fields = ['title', 'pub_date', 'read', 'comment', 'image']


class BookSerializerV2(serializers.ModelSerializer):
    class Meta:
        model = BookInfo
        fields = ['title', 'pub_date', 'read', 'comment']

說明:

  • 根據不同的版本號,可以對response返回內容進行控制,我們設置2個不同的Book模型的serializer類對應不同的版本
  • 2個序列化類返回的字段不同
  • BookSerializerV2fields中沒有包含 image ,那麼就應該把屬性定義去掉,不然會拋出錯誤

3.1.4、views

class BookView(ListAPIView):
    queryset = BookInfo.objects.all()
    serializer_class = BookSerializer

    def get_serializer_class(self):
        if self.request.version == "v2":
            return BookSerializerV2
        return self.serializer_class

說明:

  • 修改BookView類,重載get_serializer_class方法
  • 通過 self.request.version 獲取捕獲到的版本號進行控制

3.1.5、訪問

我們在請求頭中添加字段Accept:application/json;version=v1,就會返回BookSerializer的序列化字段,也就是有image字段

我們在請求頭中添加字段Accept:application/json;version=v2,就會返回BookSerializerV2的序列化字段,也就是沒有image字段

3.2、URLPathVersioning

此方案要求客戶端將版本指定為URL路徑的一部分。

3.2.1、http訪問方式

GET /v1/bookings/ HTTP/1.1

Host: example.com

Accept: application/json

說明:

版本控制出現在url路徑中,但是具體的這個 v1 出現在哪個部分,取決於url路由配置中的情況

3.2.2、settings

REST_FRAMEWORK = {
	'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
        'DEFAULT_VERSION': 'v1',
        'ALLOWED_VERSIONS': ['v1', 'v2'],
}

3.2.3、urls

子應用的urls.py中:

urlpatterns = [
    path('<str:version>/books/', views.BookView.as_view()),
]

說明:

設置版本控制在最後,訪問url是類似:http://127.0.0.1:8000/api/v2/books/

3.2.4、訪問

我們在配置好url後,在url中輸入v1,就會訪問v1版本的接口

url中輸入v2,就會訪問v2版本的接口

3.3、NamespaceVersioning

對於客戶端,此方案與URLPathVersioning相同。唯一的區別是,它是如何在 Django 應用程序中配置的,因為它使用URL conf中的命名空間而不是URL conf中的關鍵字參數。

使用此方案,request.version屬性是根據與傳入請求的路徑匹配的 namespace 確定的。

如果你隻需要一個簡單的版本控制方案URLPathVersioningNamespaceVersioning都是合適的。URLPathVersioning這種方法可能更適合小型項目,對於更大的項目來說NamespaceVersioning可能更容易管理。

3.3.1、http訪問方式

GET v1/something/ HTTP/1.1

Host: example.com

3.3.2、settings

REST_FRAMEWORK = {
	'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.NamespaceVersioning',
        'DEFAULT_VERSION': 'v1',
        'ALLOWED_VERSIONS': ['v1', 'v2'],
}

3.3.3、urls

根urls.py中:

urlpatterns = [
    path('v1/api/', include('api.urls', namespace='v1')),
    path('v2/api/', include('api.urls', namespace='v2')),
]

說明:

增加瞭2個v1v2的不同的路由配置

3.3.4、訪問

訪問v1版本

訪問v2版本

其餘HostNameVersioningQueryParameterVersioning用的不多,想瞭解的可以查詢官方文檔

以上就是淺析Django接口版本控制的詳細內容,更多關於Django接口版本控制的資料請關註WalkonNet其它相關文章!

推薦閱讀: