目錄
- 一、前言
- 二、配置
- 三、drf內(nèi)置的5個版本控制類
- 3.1、AcceptHeaderVersioning
- 3.1.1、http訪問方式
- 3.1.2、settings
- 3.1.3、serializers
- 3.1.4、views
- 3.1.5、訪問
- 3.2、URLPathVersioning
- 3.2.1、http訪問方式
- 3.2.2、settings
- 3.2.3、urls
- 3.2.4、訪問
- 3.3、NamespaceVersioning
- 3.3.1、http訪問方式
- 3.3.2、settings
- 3.3.3、urls
- 3.3.4、訪問
一、前言
在RESTful
規(guī)范中,有關(guān)版本的問題,用restful
規(guī)范做開放接口的時候,用戶請求API
,系統(tǒng)返回數(shù)據(jù)。但是難免在系統(tǒng)發(fā)展的過程中,不可避免的需要添加新的資源,或者修改現(xiàn)有資源。因此,改動升級必不可少,但是,作為平臺開發(fā)者,應(yīng)該知道:一旦API
開放出去,有人開始用了,平臺的任何改動都需要考慮對當前用戶的影響。因此,做開放平臺,從第一個API
的設(shè)計就需要開始API
的版本控制策略問題,API
的版本控制策略就像是開放平臺和平臺用戶之間的長期協(xié)議,其設(shè)計的好壞將直接決定用戶是否使用該平臺,或者說用戶在使用之后是否會因為某次版本升級直接棄用該平臺。
二、配置
有兩種配置方案,一種是在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:當版本控制信息不存在時用于設(shè)置request.version的默認值,默認設(shè)置為None。
- ALLOWED_VERSIONS:允許的版本號,譬如:['v1', 'v2']。區(qū)分大小寫,如果請求的版本號不在此列表中,拋出錯誤,上述的 DEFAULT_VERSION 的值必須是列表中的值,None除外
- VERSION_PARAM:版本控制參數(shù)的字符串,默認就是version,一般不修改
2.2、視圖配置
views.py
# 僅僅指定 版本控制類
class ProfileList(APIView):
# 指定 版本控制類
versioning_class = versioning.QueryParameterVersioning
三、drf內(nèi)置的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'],
}
說明:
- 設(shè)置版本控制類為
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']
說明:
- 根據(jù)不同的版本號,可以對
response
返回內(nèi)容進行控制,我們設(shè)置2個不同的Book
模型的serializer
類對應(yīng)不同的版本
- 2個序列化類返回的字段不同
BookSerializerV2
的 fields
中沒有包含 image
,那么就應(yīng)該把屬性定義去掉,不然會拋出錯誤
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
說明:
版本控制出現(xiàn)在url
路徑中,但是具體的這個 v1
出現(xiàn)在哪個部分,取決于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
子應(yīng)用的urls.py中:
urlpatterns = [
path('str:version>/books/', views.BookView.as_view()),
]
說明:
設(shè)置版本控制在最后,訪問url
是類似:http://127.0.0.1:8000/api/v2/books/
3.2.4、訪問
我們在配置好url
后,在url
中輸入v1,就會訪問v1版本的接口
在url
中輸入v2,就會訪問v2版本的接口
3.3、NamespaceVersioning
對于客戶端,此方案與URLPathVersioning
相同。唯一的區(qū)別是,它是如何在 Django
應(yīng)用程序中配置的,因為它使用URL conf
中的命名空間而不是URL conf
中的關(guān)鍵字參數(shù)。
使用此方案,request.version
屬性是根據(jù)與傳入請求的路徑匹配的 namespace
確定的。
如果你只需要一個簡單的版本控制方案URLPathVersioning
和NamespaceVersioning
都是合適的。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個v1
和v2
的不同的路由配置
3.3.4、訪問
訪問v1
版本
訪問v2
版本
其余HostNameVersioning
和QueryParameterVersioning
用的不多,想了解的可以查詢官方文檔
以上就是淺析Django接口版本控制的詳細內(nèi)容,更多關(guān)于Django接口版本控制的資料請關(guān)注腳本之家其它相關(guān)文章!
您可能感興趣的文章:- 使用Django開發(fā)簡單接口實現(xiàn)文章增刪改查
- python 運用Django 開發(fā)后臺接口的實例
- Python利用Django如何寫restful api接口詳解
- python采用django框架實現(xiàn)支付寶即時到帳接口