浅析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

基于请求头的版本控制，这种方式也是最推荐的方式

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字段

3.2、urlpathversioning

此方案要求客户端将版本指定为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版本的接口

3.3、namespaceversioning

对于客户端，此方案与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用的不多，想了解的可以查询官方文档

以上就是浅析django接口版本控制的详细内容，更多关于django接口版本控制的资料请关注其它相关文章！