Django REST framework API版本管理【通过GET参数传递】

API版本

在开发过程中可能会有多版本的API，因此需要对API进行管理。django drf中对于版本的管理也很方便。

http://www.example.com/api/v1/info

http://www.example.com/api/v2/info

上面这种形式就是很常见的版本管理

在restful规范中，后端的API需要体现出版本

在django drf中，共有三种形式的版本管理

1. 通过GET参数传递
2. 通过URL路由进行传递
3. 通过请求头进行传递

下面将对这三种方法逐一介绍

通过get请求传递版本信息

视图函数代码

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.versioning import QueryParameterVersioning


class HomeView(APIView):
  versioning_class = QueryParameterVersioning
  def 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.dispatch
      return Response({"code": 123123, "Home": "Home"})
1
2
3
4
5
6
7
8
9
10
11
12
13
14

urls.py

from django.urls import path
from app01.views import HomeView

urlpatterns = [
    path("home/", HomeView.as_view(), name="home"),
]
1
2
3
4
5
6

在项目的settings.py文件中，我们还需要进行三个配置

REST_FRAMEWORK = {
    # get请求的默认参数名称
    "VERSION_PARAM": "version",
    # 默认的版本
    "DEFAULT_VERSION": "v1",
    # 允许的版本
    "ALLOWED_VERSIONS": ["v1", "v2", "v3", "v111"]
}
1
2
3
4
5
6
7
8

其中，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.1
    Host: example.com
    Accept: 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
    # 用来方向生成URL
    def 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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

QueryParameterVersioning类继承自BaseVersioing类。在BaseVersioing类中，有三个默认的定义：

class BaseVersioning:
    default_version = api_settings.DEFAULT_VERSION
    allowed_versions = api_settings.ALLOWED_VERSIONS
    version_param = api_settings.VERSION_PARAM
1
2
3
4

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，程序报错，不合格的版本信息