DRF框架API版本管理实现方法解析


Posted in Python onAugust 21, 2020

API 不可能一成不变,无论是新增或者删除已有 API,都会对调用它的客户端产生影响。如果对 API 的增删没有管理,随着 API 的增增减减,调用它的客户端就会逐渐陷入迷茫,到底哪个 API 是可用的?为什么之前可用的 API 又不可用了,新增了哪些 API 可以使用?为了方便 API 的管理,我们引入版本功能。

给 API 打上版本号,在某个特定版本下,原来已有的 API 总是可用的。如果要对 API 做重大变更,可以发布一个新版本的 API,并及时提醒用户 API 已变更,敦促用户迁移到新的 API,这样可以给客户端提供一个缓冲过渡期,不至于昨天能用的 API,今天突然报错了。

django-rest-framework 提供了多个 API 版本辅助类,分别实现不同的 API 版本管理方式。比较实用的有:

AcceptHeaderVersioning

这个类要求客户端在 HTTP 的 Accept 请求头加上版本号以表明想请求的 API 版本,例如如下请求:

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

这将请求版本号为 1.0 的接口。

URLPathVersioning

这个类要求客户端在请求的 url 中指定版本号,一个缺点是你在书写 URL 模式时,必须包含关键字为 version 的模式,例如官网的一个例子:

urlpatterns = [
  url(
    r'^(?P<version>(v1|v2))/bookings/$',
    bookings_list,
    name='bookings-list'
  ),
  url(
    r'^(?P<version>(v1|v2))/bookings/(?P<pk>[0-9]+)/$',
    bookings_detail,
    name='bookings-detail'
  )
]

这样的话很不方便,因此我们一般不使用。

NamespaceVersioning

和上面提到的 URLPathVersioning 类似,只不过版本号不是在 URL 模式中指定,而是通过 namespace 参数指定 (稍后我们将看到它的具体用法)。

当然,django-rest-framework 还提供了其它诸如 HostNameVersioning、QueryParameterVersioning 的版本管理辅助类,可自行查看文档了解:https://www.django-rest-framework.org/api-guide/versioning/

综合来看,NamespaceVersioning 模式便于 URL 的设计与管理,因此我们的博客应用决定采用这种 API 版本管理方式。

为了开启 api 版本管理,在项目的配置中加入如下配置:

settings/common.py
REST_FRAMEWORK = {
  'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.NamespaceVersioning',
  'DEFAULT_VERSION': 'v1'
}

以上两项设置分别全局指定使用的 API 版本管理方式和客户端缺省版本号的情况下默认请求的 API 版本。尽管这些配置项也可以在单个视图或者视图集的范围内指定,但是,统一的版本管理模式更为可取,因此我们在全局配置中指定。

接着在注册的 API 接口前带上版本号:

blogproject/urls.py
urlpatterns = [
  # ...
  path("api/v1/", include((router.urls, "api"), namespace="v1")),
]

注意这里比之前多了个 namespace 参数,参数值为 v1,代表包含的 URL 模式均属于 v1 这个命名空间。还有一点需要注意,对于 include 函数,如果指定了 namespace 的值,第一个参数必须是一个元组,形式为:(url_patterns, app_name),这里我们将 app_name 指定为 api。

一旦我们开启了版本管理,所有请求对象 request 就会多出一个属性 version,其值为用户请求的版本号(如果没有指定,就为默认的 DEFAULT_VERSION 的值)。因此,我们可以在请求中针对不同版本的请求执行不同的代码逻辑。比如我们的博客修改文章列表 API,序列化器对返回数据的字段做了一些改动,发布在版本 v2,那么可以根据用户用户请求的版本,返回不同的数据,即新增了 API,又保持对原 api 的兼容:

if request.version == 'v1':
	return PostSerializerV1()
return PostSerializer

if 分支可以视为一段临时代码,我们可以通过适当的方式提醒用户,API 已经更改,请尽快迁移到新的版本 v2,并且在未来的某个时间,确认大部分用户都成功迁移到新版api后移除掉这些代码,并将默认版本设为v2,这样原本的 v1 版本的 API 就彻底被废弃了。

当然,我们目前的博客接口还暂时没有需要修改升级的地方,不过为了测试 API 版本管理的设置是否生效了,我们认为添加一个测试用的视图集,在里面做针对不同版本请求的处理,看看不同版本的请求下是否会返回符合预期的不同内容。

首先在 blog/views.py 中加一个简单的测试视图集,这个视图集中有个测试用的接口,接口处理逻辑是根据不同的版本号,返回不同的内容:

class ApiVersionTestViewSet(viewsets.ViewSet):
  @action(
    methods=["GET"], detail=False, url_path="test", url_name="test",
  )
  def test(self, request, *args, **kwargs):
    if request.version == "v1":
      return Response(
        data={
          "version": request.version,
          "warning": "该接口的 v1 版本已废弃,请尽快迁移至 v2 版本",
        }
      )
    return Response(data={"version": request.version})

当然视图集别忘了在 router 中注册:

blogproject/urls.py

blogproject/urls.py

# 仅用于 API 版本管理测试
router.register(
  r"api-version", blog.views.ApiVersionTestViewSet, basename="api-version"
)

这相当于一次接口版本升级,我们再加入 v2 命名空间的接口:

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

可以看到,包含的 URL 都是一样的,只是 namespace 是 v2。

来测试一下效果,启动开发服务器,先访问版本号为 v1 的测试接口,请求返回结果如下,可以看到如期返回了 v1 版本下的内容:

GET /api/v1/api-version/test/
HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
{
  "version": "v1",
  "warning": "该接口的 v1 版本已废弃,请尽快迁移至 v2 版本"
}

再访问版本号为 v2 的测试接口,返回的内容就是 v2 了。

GET /api/v2/api-version/test/

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
  "version": "v2"
}

对于其它接口,无论 v1,v2 版本的接口均可以访问,这样就相当于完成了一次兼容的接口升级。

以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持三水点靠木。

Python 相关文章推荐
Python字符转换
Sep 06 Python
Python跳出循环语句continue与break的区别
Aug 25 Python
python+opencv实现动态物体追踪
Jan 09 Python
python模拟表单提交登录图书馆
Apr 27 Python
python对离散变量的one-hot编码方法
Jul 11 Python
Python实现的特征提取操作示例
Dec 03 Python
pytorch使用Variable实现线性回归
May 21 Python
Python3 Click模块的使用方法详解
Feb 12 Python
Python3使用腾讯云文字识别(腾讯OCR)提取图片中的文字内容实例详解
Feb 18 Python
Numpy一维线性插值函数的用法
Apr 22 Python
Python小白垃圾回收机制入门
Jun 09 Python
python 实现压缩和解压缩的示例
Sep 22 Python
Django rest framework分页接口实现原理解析
Aug 21 #Python
Python -m参数原理及使用方法解析
Aug 21 #Python
python使用布隆过滤器的实现示例
Aug 20 #Python
QT5 Designer 打不开的问题及解决方法
Aug 20 #Python
Python配置pip国内镜像源的实现
Aug 20 #Python
Python使用lambda抛出异常实现方法解析
Aug 20 #Python
浅谈对python中if、elif、else的误解
Aug 20 #Python
You might like
PHP最常用的ini函数分析 针对PHP.ini配置文件
2010/04/22 PHP
基于xcache的配置与使用详解
2013/06/18 PHP
php实现的获取网站备案信息查询代码(360)
2013/09/23 PHP
权威JavaScript 中的内存泄露模式
2007/08/13 Javascript
location.href语句与火狐不兼容的问题
2010/07/04 Javascript
ZeroClipboard插件实现多浏览器复制功能(支持firefox、chrome、ie6)
2014/08/30 Javascript
JS实现文字向下滚动完整实例
2015/02/06 Javascript
JavaScript实现简单Tip提示框效果
2016/04/20 Javascript
JavaScript实现Fly Bird小游戏
2016/12/15 Javascript
vuejs响应用户事件(如点击事件)
2017/03/14 Javascript
BootStrap点击保存后实现模态框自动关闭的思路(模态框)
2017/09/26 Javascript
VUE饿了么树形控件添加增删改功能的示例代码
2017/10/17 Javascript
浅谈Vue SPA 首屏加载优化实践
2017/12/15 Javascript
使用Vuex解决Vue中的身份验证问题
2018/09/28 Javascript
JavaScript简单实现的仿微博留言功能示例
2019/01/17 Javascript
关于vue-cli 3配置打包优化要点(推荐)
2019/04/22 Javascript
Python多线程编程(七):使用Condition实现复杂同步
2015/04/05 Python
Python的Flask框架应用程序实现使用QQ账号登录的方法
2016/06/07 Python
浅谈Matplotlib简介和pyplot的简单使用——文本标注和箭头
2018/01/09 Python
Python学习笔记之图片人脸检测识别实例教程
2019/03/06 Python
Django网络框架之创建虚拟开发环境操作示例
2019/06/06 Python
详解Python修复遥感影像条带的两种方式
2020/02/23 Python
李宁官方网店:中国运动品牌
2017/11/02 全球购物
香港最大的洋酒零售连锁店:屈臣氏酒窖(Watson’s Wine)
2018/12/10 全球购物
HelloFresh奥地利:立即订购烹饪盒
2019/02/22 全球购物
学习十八大精神心得体会
2013/12/31 职场文书
学习心得体会
2014/01/01 职场文书
教书育人演讲稿
2014/09/11 职场文书
中职毕业生自我鉴定
2014/09/13 职场文书
商业用房租赁协议书
2014/10/13 职场文书
考研复习计划
2015/01/19 职场文书
介绍信的写法
2015/01/31 职场文书
岳庙导游词
2015/02/04 职场文书
经典爱情感言
2015/08/03 职场文书
情感电台广播稿
2015/08/18 职场文书
会计手工模拟做账心得体会
2016/01/22 职场文书