API版本
在开发过程中可能会有多版本的API,因此需要对API进行管理。django drf中对于版本的管理也很方便。
http://www.example.com/api/v1/info
http://www.example.com/api/v2/info
上面这种形式就是很常见的版本管理
在restful规范中,后端的API需要体现出版本
在django drf中,共有三种形式的版本管理
- 通过GET参数传递
- 通过URL路由进行传递
- 通过请求头进行传递
下面将对这三种方法逐一介绍
通过get请求传递版本信息
视图函数代码
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.versioning import QueryParameterVersioningclass HomeView(APIView):versioning_class = QueryParameterVersioningdef get(self, request):print("api_version=", request.version)print(request.versioning_scheme)url = request.versioning_scheme.reverse("home", request=request)print("drf反向生成的URL为", url)self.dispatchreturn Response({"code": 123123, "Home": "Home"})
urls.py
from django.urls import path
from app01.views import HomeViewurlpatterns = [path("home/", HomeView.as_view(), name="home"),
]
在项目的settings.py
文件中,我们还需要进行三个配置
REST_FRAMEWORK = {# get请求的默认参数名称"VERSION_PARAM": "version",# 默认的版本"DEFAULT_VERSION": "v1",# 允许的版本"ALLOWED_VERSIONS": ["v1", "v2", "v3", "v111"]
}
其中,VERSION_PARAM
代表get请求的默认参数名,后面请求接口http://127.0.0.1:8000/home/?version=v1时,django会自动将参数中的version获取到,并赋值到request.version中。
具体的可以参考drf中通过get请求传递版本对应部分的源码
class QueryParameterVersioning(BaseVersioning):"""GET /something/?version=0.1 HTTP/1.1Host: example.comAccept: application/json"""invalid_version_message = _('Invalid version in query parameter.')# 用来提取版本def determine_version(self, request, *args, **kwargs):# 从请求的参数中先获取有没有版本,如果没有版本则赋值为默认的版本参数version = request.query_params.get(self.version_param, self.default_version)if not self.is_allowed_version(version):raise exceptions.NotFound(self.invalid_version_message)return version# 用来方向生成URLdef reverse(self, viewname, args=None, kwargs=None, request=None, format=None, **extra):url = super().reverse(viewname, args, kwargs, request, format, **extra)if request.version is not None:return replace_query_param(url, self.version_param, request.version)return url
QueryParameterVersioning类继承自BaseVersioing类。在BaseVersioing类中,有三个默认的定义:
class BaseVersioning:default_version = api_settings.DEFAULT_VERSIONallowed_versions = api_settings.ALLOWED_VERSIONSversion_param = api_settings.VERSION_PARAM
default_version
代表默认的版本,会自动去全局配置中寻找,如果全局中没有配置则去局部进行寻找
allowed_versions
代表允许的版本号,会自动取settings.py
文件中去读取相应的配置
version_param
代表get请求参数中的关键字,例如http://127.0.0.1:8000/home/?version=v1 例如,若settings.py
文件中配置了此url中的version_param
值为version,那么version就是获取版本的关键字(本质上是字典的键)
接下来看效果演示,这里通过postman来模拟get和post请求。
- 首先,这里我没有在URL中携带版本信息,由于我在全局配置中写了默认是v1,并且关键字是version,因此会帮我按照这个配置信息反向生成一个url链接。
- 接下来的请求我会携带version参数,可以看到响应成功,输出api版本信息并反向生成了url
- 接下来我换一个关键词使用?xx=v3,drf会按照之前的配置,默认使用v1参数
- 接下来我会使用不在
ALLOWED_VERSIONS
中的版本信息,v1000,程序报错,不合格的版本信息