【djangorestframework】12、Routers(路由)

Routers

• 资源路由允许你快速声明给定资源控制器的所有公共路由。而不是为了索引声明单独的路由...灵活多样的路由在一行代码中声明它们。--Ruby on Rails文档
• 一些Web框架(如Rails)提供了自动确定应用程序的URL应该如何映射到处理传入请求的逻辑的功能。
• REST framework增加了对Django自动URL路由的支持，并为你提供一种简单，快速和一致的方式，将视图逻辑连接到一组URL

用法(Usage)

• 这是一个使用SimpleRouter的简单URL conf的示例。

from rest_framework import routers

router = routers.SimpleRouter()
router.register(r'users', UserViewSet)
router.register(r'accounts', AccountViewSet)
urlpatterns = router.urls

• register()方法有两个必需参数：
• prefix--用于此路由集的URL前缀
• vieewset--视图集类
• 可选的，你还可以指定一个附件参数：
• base_name--用于创建的URL名称的基础。如果未设置，basename将根据视图集的queryset属性(如果它有的话)自动生成。注意，如果视图集不包含queryset属性，那么在注册视图集时必须设置base_name
• 上面的示例将生成以下URL模式：
• URL模式：^users/$ 名称: 'user-list'
• URL模式：^users/{pk}/$ 名称：'user-detail'
• URL模式：^accounts/$ 名称：'account-list'
• URL模式：^accounts/{pk}/$ 名称：'account-detail'
• 注意：
• base_name参数用于指定视图名称模式的初始部分。在上面的示例中，是user或account部分。
• 通常，你不需要指定base_name参数，但是如果你有一个定义了自定义get_queryset方法的视图集，那么该视图集可能没有.queryset属性集。如果你尝试注册该视图集，你将看到如下错误：

'base_name' argument not specified, and could not automatically determine the name from the viewset, as it does not have a '.queryset' attribute.

• 这意味着你在注册视图集时需要显式设置base_name参数，因为它无法从模型名称自动确定。

使用路由器的include(Using include with routers)

• 路由器实例上的.urls属性仅仅是URL模式的标准列表。关于如何包含这些URL，有许多不同的样式。
• 例如，你可以将router.urls附加到现有视图列表中...

router = routers.SimpleRouter()
router.register(r'users', UserViewSet)
router.register(r'accounts', AccountViewSet)

urlpatterns = [
    url(r'^forgot-password/$', ForgotPasswordFormView.as_view()),
]

urlpatterns += router.urls

• 另外，你可以使用Django的include函数，像这样...

urlpatterns = [
    url(r'^forgot-password/$', ForgotPasswordFormView.as_view()),
    url(r'^', include(router.urls)),
]

• 你可以在应用程序命名空间中使用include:

urlpatterns = [
    url(r'^forgot-password/$', ForgotPasswordFormView.as_view()),
    url(r'^api/', include((router.urls, 'app_name'))),
]

• 或应用程序和实例命名空间:

urlpatterns = [
    url(r'^forgot-password/$', ForgotPasswordFormView.as_view()),
    url(r'^api/', include((router.urls, 'app_name'), namespace='instance_name')),
]

• 有关详细信息，请参阅Django的URL命名空间文档和include API参考
• 注意：
• 如果对超链接序列化器使用命名空间，则还需要确保序列化器上的任何view_name参数都能正确反应命名空间。在上面的示例中，你需要为超链接到用户详细视图的序列化字段包含一个诸如vie_name='api:user=detail'之类的参数。
• 使用类似%(model-name)-detail模式自动生成view_name。除非你的模型名称实际上发生冲突，否则在使用超链接序列化器时，最好不要对Django REST framework视图进行命名。

额外操作的路由(Routing for extra actions)

• 视图集可以通过使用@action装饰器装饰方法来标记路由的额外操作。这些额外的操作将包含在生成的路由中。例如，在UserViewSet类中给出set_password方法：

from myapp.permissions import IsAdminOrIsSelf
from rest_framework.decorators import action

class UserViewSet(ModelViewSet):
    ...

    @action(methods=['post'], detail=True, permission_classes=[IsAdminOrIsSelf])
    def set_password(self, request, pk=None):
        ...

• 将生成以下路由：
• URL模式：^users/{pk}/set_password/$
• URL名称：'user-set-password'
• 默认情况下，URL模式基于方法名，URL名称是ViewSet.basename和带连字符的方法名称的组合。如果你不想使用这些值中的任何一个默认值，你可以向@action装饰器提供url_path和url_name参数
• 例如，如果要将自定义操作的URL更改为^users/{pk}/change-password/$，则可以编写：

from myapp.permissions import IsAdminOrIsSelf
from rest_framework.decorators import action

class UserViewSet(ModelViewSet):
    ...

    @action(methods=['post'], detail=True, permission_classes=[IsAdminOrIsSelf],
            url_path='change-password', url_name='change_password')
    def set_password(self, request, pk=None):
        ...

• 上面的示例现在将生成以下URL模式：
• URL path：^users/{pk}/change-password/$
• url name：'user-change-password'

API指南(API Guide)

SimpleRouter

• 此路由器包含标准list，create， retrieve， update，partial_update和destroy操作的路由。视图集还可以使用@action装饰器标记被路由的其他方法。