浅析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个序列化类返回的字段不同
  • BookSerializerV2fields中没有包含 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 确定的。

如果你只需要一个简单的版本控制方案URLPathVersioningNamespaceVersioning都是合适的。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个v1v2的不同的路由配置

4.访问

访问v1版本

访问v2版本

其余HostNameVersioningQueryParameterVersioning用的不多,想了解的可以查询官方文档

以上就是浅析Django接口版本控制的详细内容,更多关于Django接口版本控制的资料请关注179885.Com其它相关文章!

猜你在找的浅析Django接口版本控制相关文章

一个项目在升级迭代的时候,不会立马抛弃旧的版本,甚至会出现多个版本共存同时维护的情况,因此需要版本控制
Intersection over Union(IoU)是一种测量在特定数据集中检测相应物体准确度的一个标准。IoU是一个简单的测量标准,只要是在输出中得出一个预测范围(bounding boxes)
DFA全称为Deterministic Finite Automaton,即确定有穷自动机。特征:有一个有限状态集合和一些从一个状态通向另一个状态的边,每条边标记有一个符号,其中一个状态是初
pycharm是一个很强大的编辑工具,很多朋友在使用过程中容易产生误操作,那么一不小心删除了,怎么恢复呢,今天就给大家介绍pycharm代码删除恢复教程,需要的朋友参考下吧
异常就是系统中的错误,程序是无法改变和处理的,文中有给大家提到异常处理机制,模块与包的相关知识,通过实例代码给大家介绍的非常详细,需要的朋友参考下吧
redis 提供两个类 Redis 和 StrictRedis, StrictRedis 用于实现大部分官方的命令,Redis 是 StrictRedis 的子类,用于向后兼用旧版本,接下来通过本文给大家分享Python
最近有童鞋向小编求助怎么样找到字符串中出现字数最多的字符呢,其实最简单的处理方法是使用max函数,max()函数用于获得给定的可迭代对象中的最大值,关于Python max函
今天给大家带来的是关于Python的相关知识,文章围绕着Python注释的用法展开,文中有非常详细的介绍及代码示例,需求的大佬可以参考下
今天来分享一篇办公干货文章,对于财务专业等学生或者公司财务人员来说,将报账发票等汇总到excel简直就是一个折磨.尤其是到年底的时候,公司的财务人员面对一大堆
介绍了手残删除python之后的补救方法,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
上大学的时候有老师不给上课的PPT,就总想有个程序能偷偷复制老师的U盘一直没有去实现,最近不想看论文就想起来这个事情了,发现其实用几行python代码就能搞定.分两
今天给大家带来的是关于Python爬虫的相关知识,文章围绕着Python scrapy展开,文中有非常详细的介绍及代码示例,需求的大佬可以参考下