django Rest Framework 系列 6 - ViewSets & Routers

官网地址：http://www.django-rest-framework.org/tutorial/6-viewsets-and-routers/

REST框架包含一个ViewSets 的抽象行为，它允许开发人员能专注于API的状态和相互作用进行建模,并基于常规约定自动构建URL。
ViewSet 类和 View 类几乎是一样的,区别是它提供了类似于read 或 update 这样的操作, 而不处理像 get 或者 put 这样的方法。

一个ViewSet 类当被实例化成一组视图时, 通常会通过使用一个路由类(Router class)来帮你处理复杂的URL定义，最终绑定到一组处理方法。

1. 使用ViewSets重构
我们看看当前的一组视图,并重构为视图集（view sets）
首先,我们重构我们的UserList 和 UserDetail 视图到单个的 UserViewSet ，我们可以删除两个视图并用一个类来替换：

from rest_framework import viewsets

class UserViewSet(viewsets.ReadOnlyModelViewSet):
    """
    This viewset automatically provides `list` and `detail` actions.
    """
    queryset = User.objects.all()
    serializer_class = UserSerializer

这里我们使用了ReadOnlyModelViewSet 类自动提供默认的 只读 操作, 我们仍然如我们使用常规视图一样设置 queryset 和 serializer_class 属性, 但我们不在需要为两个不同的类提供相同的信息。

接下来,我们开始替换SnippetList, SnippetDetail 和 SnippetHighlight 类视图, 我们可以删除这三个视图, 同样替换成一个单个的类：

from rest_framework.decorators import detail_route

class SnippetViewSet(viewsets.ModelViewSet):
    """
    This viewset automatically provides `list`, `create`, `retrieve`,
    `update` and `destroy` actions.

    Additionally we also provide an extra `highlight` action.
    """
    queryset = Snippet.objects.all()
    serializer_class = SnippetSerializer
    permission_classes = (permissions.IsAuthenticatedOrReadOnly,
                          IsOwnerOrReadOnly,)

    @detail_route(renderer_classes=[renderers.StaticHTMLRenderer])
    def highlight(self, request, *args, **kwargs):
        snippet = self.get_object()
        return Response(snippet.highlighted)

    def perform_create(self, serializer):
        serializer.save(owner=self.request.user)

这次,为了获取完整的默认读写操作,我们使用了ModelViewSet 类。
注意, 我们还使用了@detail_route 装饰器来创建一个名为highlight自定义动作，这个装饰器可用于添加不符合标准的 create/update/delete 样式的任何自定义端。
默认情况下, 使用@detail_route 装饰器的自定义操作将响应 GET 请求, 如果我们想响应 POST 请求, 我们可以使用 method 参数。
默认情况下，自定义操作的URL取决于方法名称本身。 如果要更改URL的构造方式，可以将url_path作为decorator的关键字参数。

2. 绑定 ViewSet 到 URL
处理方法只能绑定到我们在URL 配置中的动作上, 让我们首先从ViewSets 中明确创建一组视图，看看会发生什么.
在 urls.py 文件中绑定 ViewSet 类到一组具体视图中

from snippets.views import SnippetViewSet, UserViewSet, api_root
from rest_framework import renderers

snippet_list = SnippetViewSet.as_view({
    'get': 'list',
    'post': 'create'
})
snippet_detail = SnippetViewSet.as_view({
    'get': 'retrieve',
    'put': 'update',
    'patch': 'partial_update',
    'delete': 'destroy'
})
snippet_highlight = SnippetViewSet.as_view({
    'get': 'highlight'
}, renderer_classes=[renderers.StaticHTMLRenderer])
user_list = UserViewSet.as_view({
    'get': 'list'
})
user_detail = UserViewSet.as_view({
    'get': 'retrieve'
})

注意， 通过为每个视图所需动作绑定http方法，我们如何从每个ViewSet 类中创建多视图。
现在, 我们绑定我们的资源到具体视图中, 我们可以想平常一样通过URL 配置注册视图

urlpatterns = format_suffix_patterns([
    url(r'^$', api_root),
    url(r'^snippets/$', snippet_list, name='snippet-list'),
    url(r'^snippets/(?P<pk>[0-9]+)/$', snippet_detail, name='snippet-detail'),
    url(r'^snippets/(?P<pk>[0-9]+)/highlight/$', snippet_highlight, name='snippet-highlight'),
    url(r'^users/$', user_list, name='user-list'),
    url(r'^users/(?P<pk>[0-9]+)/$', user_detail, name='user-detail')
])

3. 使用路由
由于我们使用 ViewSet 类而不是View 类, 我们实际上不需要自己设计URL配置。 通过一个 Router 类会自动处理 视图和 url 连接资源。 我们所需要做的就是通过路由注册一个适当的视图集。
现在我们重写urls.py 文件：

from django.conf.urls import url, include
from snippets import views
from rest_framework.routers import DefaultRouter

# Create a router and register our viewsets with it.
router = DefaultRouter()
router.register(r'snippets', views.SnippetViewSet)
router.register(r'users', views.UserViewSet)

# The API URLs are now determined automatically by the router.
# Additionally, we include the login URLs for the browsable API.
urlpatterns = [
    url(r'^', include(router.urls)),
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

通过路由注册视图集合提供的url模式很相似， 我们包含了两个参数：
. 视图的 url 前缀
. 视图集本身
我们使用的这个DefaultRouter 类会自动为我们创建 API 根视图。我们现在可以从我们的views 模块中删除api_root 方法

4. views 和 viewsets 之间的权衡
使用 viewsets 可以是一个非常有用的抽象。 它有助于确保您的API中的URL约定是一致的，最大限度地减少您编写的代码量，并允许您专注于API提供的交互和表示，而不是URL conf的具体内容。
这并不意味着这总是好的选择，就像在权衡使用基于类的视图还是是基于函数的视图一样。