一、前言

在RESTful規(guī)范中，有關(guān)版本的問(wèn)題，用restful規(guī)范做開放接口的時(shí)候，用戶請(qǐng)求API，系統(tǒng)返回?cái)?shù)據(jù)。但是難免在系統(tǒng)發(fā)展的過(guò)程中，不可避免的需要添加新的資源，或者修改現(xiàn)有資源。因此，改動(dòng)升級(jí)必不可少，但是，作為平臺(tái)開發(fā)者，應(yīng)該知道：一旦API開放出去，有人開始用了，平臺(tái)的任何改動(dòng)都需要考慮對(duì)當(dāng)前用戶的影響。因此，做開放平臺(tái)，從第一個(gè)API的設(shè)計(jì)就需要開始API的版本控制策略問(wèn)題，API的版本控制策略就像是開放平臺(tái)和平臺(tái)用戶之間的長(zhǎng)期協(xié)議，其設(shè)計(jì)的好壞將直接決定用戶是否使用該平臺(tái)，或者說(shuō)用戶在使用之后是否會(huì)因?yàn)槟炒伟姹旧?jí)直接棄用該平臺(tái)。

二、配置

有兩種配置方案，一種是在settings中全局配置，第二種是在視圖中指定，不過(guò)此方法一般不使用，因?yàn)榘姹究刂拼蟛糠智闆r下是全局的處理情況

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'，有多種方式。默認(rèn)為None，為None時(shí)，框架變量request.version將始終返回None
• DEFAULT_VERSION：當(dāng)版本控制信息不存在時(shí)用于設(shè)置request.version的默認(rèn)值，默認(rèn)設(shè)置為None。
• ALLOWED_VERSIONS：允許的版本號(hào)，譬如：['v1', 'v2']。區(qū)分大小寫，如果請(qǐng)求的版本號(hào)不在此列表中，拋出錯(cuò)誤，上述的 DEFAULT_VERSION 的值必須是列表中的值，None除外
• VERSION_PARAM：版本控制參數(shù)的字符串，默認(rèn)就是version，一般不修改

2.2、視圖配置

views.py

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

三、drf內(nèi)置的5個(gè)版本控制類

3.1、AcceptHeaderVersioning

基于請(qǐng)求頭的版本控制，這種方式也是最推薦的方式

3.1.1、http訪問(wèn)方式

GET /bookings/ HTTP/1.1

Host: example.com

Accept: application/json; version=1.0

在上面的示例請(qǐng)求中request.version屬性將返回字符串'1.0'。 基于accept headers 的版本控制通常被認(rèn)為是最佳實(shí)踐，盡管其他版本控制方式可能適合你的客戶端需求。

3.1.2、settings

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

說(shuō)明：

• 設(shè)置版本控制類為AcceptHeaderVersioning
• 沒(méi)有檢測(cè)到version時(shí)，默認(rèn)是v1版本
• 允許的2個(gè)版本型號(hào)為：['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']

說(shuō)明：

• 根據(jù)不同的版本號(hào)，可以對(duì)response返回內(nèi)容進(jìn)行控制，我們?cè)O(shè)置2個(gè)不同的Book模型的serializer類對(duì)應(yīng)不同的版本
• 2個(gè)序列化類返回的字段不同
• BookSerializerV2 的 fields中沒(méi)有包含 image ，那么就應(yīng)該把屬性定義去掉，不然會(huì)拋出錯(cuò)誤

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

說(shuō)明：

• 修改BookView類，重載get_serializer_class方法
• 通過(guò) self.request.version 獲取捕獲到的版本號(hào)進(jìn)行控制

3.1.5、訪問(wèn)

我們?cè)谡?qǐng)求頭中添加字段Accept:application/json;version=v1，就會(huì)返回BookSerializer的序列化字段，也就是有image字段

我們?cè)谡?qǐng)求頭中添加字段Accept:application/json;version=v2，就會(huì)返回BookSerializerV2的序列化字段，也就是沒(méi)有image字段

3.2、URLPathVersioning

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

3.2.1、http訪問(wèn)方式

GET /v1/bookings/ HTTP/1.1

Host: example.com

Accept: application/json

說(shuō)明：

版本控制出現(xiàn)在url路徑中，但是具體的這個(gè) v1 出現(xiàn)在哪個(gè)部分，取決于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()),
]

說(shuō)明：

設(shè)置版本控制在最后，訪問(wèn)url是類似：http://127.0.0.1:8000/api/v2/books/

3.2.4、訪問(wèn)

我們?cè)谂渲煤?code>url后，在url中輸入v1，就會(huì)訪問(wèn)v1版本的接口

在url中輸入v2，就會(huì)訪問(wèn)v2版本的接口

3.3、NamespaceVersioning

對(duì)于客戶端，此方案與URLPathVersioning相同。唯一的區(qū)別是，它是如何在 Django 應(yīng)用程序中配置的，因?yàn)樗褂?code>URL conf中的命名空間而不是URL conf中的關(guān)鍵字參數(shù)。

使用此方案，request.version屬性是根據(jù)與傳入請(qǐng)求的路徑匹配的 namespace 確定的。

如果你只需要一個(gè)簡(jiǎn)單的版本控制方案URLPathVersioning和NamespaceVersioning都是合適的。URLPathVersioning這種方法可能更適合小型項(xiàng)目，對(duì)于更大的項(xiàng)目來(lái)說(shuō)NamespaceVersioning可能更容易管理。

3.3.1、http訪問(wèn)方式

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')),
]

說(shuō)明：

增加了2個(gè)v1和v2的不同的路由配置

3.3.4、訪問(wèn)

訪問(wèn)v1版本

訪問(wèn)v2版本

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

以上就是淺析Django接口版本控制的詳細(xì)內(nèi)容，更多關(guān)于Django接口版本控制的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

最新評(píng)論