Django drf Versioning

Versioning

对接口进行版本控制只是一种杀死已部署客户端的“礼貌”方式。— Roy Fielding.

API 版本控制允许你在不同的客户端之间更改行为. REST framework 提供了许多不同的版本控制方案。

版本控制由传入的客户端请求决定，可以基于请求的URL，也可以基于请求头。

有许多有效的方法可以进行版本控制。无版本控制的系统也可能是合适的，特别是如果你正在为一个长期系统进行工程设计，而这个系统有多个超出你控制范围的客户端。

使用REST框架进行版本控制

当启用API版本控制，request.version 属性将包含与传入客户端请求中请求的版本相对应的字符串。

默认情况下，版本控制没有启用，request.version 将总是返回 None。

根据版本改变行为

如何改变API的行为取决于你自己，但是一个你通常想要的例子是在新版本中切换到不同的序列化样式。例如:

def get_serializer_class(self):
    if self.request.version == 'v1':
        return AccountSerializerVersion1
    return AccountSerializer

反向解析版本化API的URL

REST framework 包含的 reverse 函数与版本控制方案相关联。你需要确保将当前 request 作为关键字参数传递进去，如下所示。

from rest_framework.reverse import reverse

reverse('bookings-list', request=request)

上述函数将应用任何适用于请求版本的URL转换。例如:

如果使用NamespacedVersioning，并且API的版本是'v1'，那么将会查找 'v1:bookings-list'，可能反向解析为类似http://example.org/v1/bookings/ 这个URL。
如果使用QueryParameterVersioning 并且API的版本是1.0，那么返回的URL可能就像这样http://example.org/bookings/?version=1.0。

版本化 API 和超链接序列化器

当将超链接序列化样式与基于URL的版本控制方案一起使用时，请确保将请求作为上下文包含在序列化程序中。

def get(self, request):
    queryset = Booking.objects.all()
    serializer = BookingsSerializer(queryset, many=True, context={'request': request})
    return Response({'all_bookings': serializer.data})

这样做将会在任何返回的URL中包含适当的版本控制。

配置版本控制方案

版本控制方案由settings中的DEFAULT_VERSIONING_CLASS为key来配置。

REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.NamespaceVersioning'
}

除非显式设置，否则DEFAULT_VERSIONING_CLASS将会是None。在这种情况下request.version属性将总是返回None。

还可以在单个视图上设置版本控制方案。通常不需要这样做，因为全局使用单一版本控制方案更有意义。如果确实需要这样做，请在视图类中使用versioning_class属性。

class ProfileList(APIView):
    versioning_class = versioning.QueryParameterVersioning

其他版本控制设置

以下设置的key也用于控制版本控制:

DEFAULT_VERSION. 当版本控制信息不存在时用于设置request.version的默认值，默认设置为None。
ALLOWED_VERSIONS. 如果设置了此值将限制版本控制方案可能返回的版本集，如果客户端请求提供的版本不在此集中，则会引发错误。请注意，用于DEFAULT_VERSION的值应该总是在ALLOWED_VERSIONS设置的集合中（除非是None）。该配置默认是 None。
VERSION_PARAM. 一个应当用于任何版本控制系统参数的字符串，例如媒体类型或URL查询参数。默认值是'version'。

你还可以通过自定义版本控制方案并使用default_version，allowed_versions和version_param类变量，在每个视图或每个视图集的基础上设置版本类加上这三个值。例如，如果你想使用URLPathVersioning：

from rest_framework.versioning import URLPathVersioning
from rest_framework.views import APIView

class ExampleVersioning(URLPathVersioning):
    default_version = ...
    allowed_versions = ...
    version_param = ...

class ExampleView(APIVIew):
    versioning_class = ExampleVersioning

API参考

AcceptHeaderVersioning

此方案要求客户端在Accept header 中将版本指定为媒体类型的一部分。该版本作为媒体类型参数包含在内，它补充了主要媒体类型。

下面是一个使用accept header版本化样式的HTTP请求示例。

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

在上面的示例请求中request.version属性将返回字符串'1.0'。基于 accept headers 的版本控制通常被认为是最佳实践，尽管其他版本控制方式可能适合你的客户端需求。

Using accept headers with vendor media types

严格地说json媒体类型未指定为包含其他参数。如果要构建明确指定的公共API，则可以考虑使用vendor media type。为此，请将渲染器配置为使用自定义媒体类型的基于JSON的渲染器：

class BookingsAPIRenderer(JSONRenderer):
    media_type = 'application/vnd.megacorp.bookings+json'

你的客户端请求现在会是这样的:

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

URLPathVersioning

此方案要求客户端将版本指定为URL路径的一部分。

GET /v1/bookings/ HTTP/1.1
Host: example.com
Accept: application/json

你的URL conf中必须包含一个使用'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相同。唯一的区别是，它是如何在 Django 应用程序中配置的，因为它使用URL conf中的命名空间而不是URL conf中的关键字参数。

GET /v1/something/ HTTP/1.1
Host: example.com
Accept: application/json

使用此方案，request.version 属性是根据与传入请求的路径匹配的 namespace 确定的。

在下面的示例中，我们给一组视图提供了两个可能出现的不同URL前缀，每个前缀在不同的命名空间下:

# bookings/urls.py
urlpatterns = [
    url(r'^$', bookings_list, name='bookings-list'),
    url(r'^(?P<pk>[0-9]+)/$', bookings_detail, name='bookings-detail')
]

# urls.py
urlpatterns = [
    url(r'^v1/bookings/', include('bookings.urls', namespace='v1')),
    url(r'^v2/bookings/', include('bookings.urls', namespace='v2'))
]

如果你只需要一个简单的版本控制方案URLPathVersioning和NamespaceVersioning都是合适的。URLPathVersioning 这种方法可能更适合小型项目，对于更大的项目来说NamespaceVersioning可能更容易管理。

HostNameVersioning

主机名版本控制方案要求客户端将请求的版本指定为URL中主机名的一部分。例如，以下是对http://v1.example.com/bookings/的HTTP请求：

GET /bookings/ HTTP/1.1
Host: v1.example.com
Accept: application/json

默认情况下，此实现期望主机名与以下简单正则表达式匹配:

^([a-zA-Z0-9]+)\.[a-zA-Z0-9]+\.[a-zA-Z0-9]+$

注意，第一组用括号括起来，表示这是主机名的匹配部分。

HostNameVersioning这种方案在调试模式下使用方案可能会很尴尬，因为你通常会访问原始IP地址，例如127.0.0.1。有各种在线教程，介绍使用自定义子域名访问本地主机，这种情况下你可能会发现这很有帮助。

如果你有基于版本将传入请求路由到不同服务器的需求，那么基于主机名的版本控制会特别有用，因为你可以为不同的 API 版本配置不同的 DNS 记录。

QueryParameterVersioning

此方案是一种在 URL 中包含版本信息作为查询参数的简单方案。例如： This scheme is a simple style that includes the version as a query parameter in the URL. For example:

GET /something/?version=0.1 HTTP/1.1
Host: example.com
Accept: application/json

Custom versioning schemes

要实现自定义版本控制方案，请继承 BaseVersioning 并重写 .determine_version 方法。

举个例子

下面的例子中使用一个自定义的 X-API-Version header来确定所请求的版本。

class XAPIVersionScheme(versioning.BaseVersioning):
    def determine_version(self, request, *args, **kwargs):
        return request.META.get('HTTP_X_API_VERSION', None)

如果你的版本化方案基于请求URL，你还需要改变版本化URL的确定方式。为此，你还应该重写类中的.reverse()方法。有关示例，请参见源代码。

w3cschool 编程狮，随时随地学编程

Django drf Versioning

Versioning

使用REST框架进行版本控制

根据版本改变行为

反向解析版本化API的URL

版本化 API 和超链接序列化器

配置版本控制方案

其他版本控制设置

API参考

AcceptHeaderVersioning

Using accept headers with vendor media types

URLPathVersioning

NamespaceVersioning

HostNameVersioning

QueryParameterVersioning

Custom versioning schemes

举个例子

Django drf 教程

Django drf API文档