Django（70）介面版本控制

Silent丿丶黑羽發表於2021-06-24
Django

前言

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

1.配置

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

1.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，一般不修改
     

1.2檢視配置

views.py

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

 

2.drf內建的5個版本控制類

  • AcceptHeaderVersioning
  • URLPathVersioning
  • NamespaceVersioning
  • HostNameVersioning
  • QueryParameterVersioning
     

2.1AcceptHeaderVersioning

基於請求頭的版本控制，這種方式也是最推薦的方式
 
1.http訪問方式

GET /bookings/ HTTP/1.1
Host: example.com
Accept: application/json; version=1.0

在上面的示例請求中request.version屬性將返回字串'1.0'。 基於accept headers 的版本控制通常被認為是最佳實踐，儘管其他版本控制方式可能適合你的客戶端需求。
 
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.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個序列化類返回的欄位不同
  • BookSerializerV2 的 fields中沒有包含 image ，那麼就應該把屬性定義去掉，不然會丟擲錯誤

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 獲取捕獲到的版本號進行控制

5.訪問
我們在請求頭中新增欄位Accept:application/json;version=v1，就會返回BookSerializer的序列化欄位，也就是有image欄位

我們在請求頭中新增欄位Accept:application/json;version=v2，就會返回BookSerializerV2的序列化欄位，也就是沒有image欄位

 

2.2URLPathVersioning

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

1.http訪問方式

GET /v1/bookings/ HTTP/1.1
Host: example.com
Accept: application/json

說明：

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

2.settings

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

3.urls
子應用的urls.py中：

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

說明：
設定版本控制在最後，訪問url是類似：http://127.0.0.1:8000/api/v2/books/

4.訪問
我們在配置好url後，在url中輸入v1，就會訪問v1版本的介面

在url中輸入v2，就會訪問v2版本的介面

 

2.3NamespaceVersioning

  對於客戶端，此方案與URLPathVersioning相同。唯一的區別是，它是如何在 Django 應用程式中配置的，因為它使用URL conf中的名稱空間而不是URL conf中的關鍵字引數。
  使用此方案，request.version屬性是根據與傳入請求的路徑匹配的 namespace 確定的。
  如果你只需要一個簡單的版本控制方案URLPathVersioning和NamespaceVersioning都是合適的。URLPathVersioning這種方法可能更適合小型專案，對於更大的專案來說NamespaceVersioning可能更容易管理。

1.http訪問方式

GET v1/something/ HTTP/1.1
Host: example.com

2.settings

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

3.urls
根urls.py中：

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

說明：

  • 增加了2個v1和v2的不同的路由配置

4.訪問
訪問v1版本

訪問v2版本

 

其餘HostNameVersioning和QueryParameterVersioning用的不多，想了解的可以查詢官方文件

相關文章