Django REST framework API 指南（6）：路由

Django REST framework API 指南（1）：请求
Django REST framework API 指南（2）：响应
Django REST framework API 指南（3）：视图
Django REST framework API 指南（4）：通用视图
Django REST framework API 指南（5）：视图集
Django REST framework API 指南（6）：路由
Django REST framework API 指南（7）：解析

官方原文链接

路由

一些 Web 框架（如 Rails）提供了一种能够自动确定应用程序的 URL 如何映射到处理请求的功能。

REST framework 增加了对 Django 自动 URL 路由的支持，并提供了一种将视图逻辑连接到一组 URL 的简单，高效和一致的方式。

用法

下面是一个使用 SimpleRouter 的简单 URL 配置示例。

from rest_framework import routers

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

register() 方法有两个必须参数：

• prefix - 设置这组路由的前缀。
• viewset - 设置对应的视图集类。

或者，您也可以指定一个附加参数：

• base_name - 用于创建的 URL 名称的基础。如果未设置，将根据视图集的 queryset 属性自动生成。请注意，如果视图集不包含 queryset 属性，则在注册视图集时必须设置 base_name。

上面的例子会生成以下 URL 模式：

• URL pattern: ^users/$ Name: 'user-list'
• URL pattern: ^users/{pk}/$ Name: 'user-detail'
• URL pattern: ^accounts/$ Name: 'account-list'
• URL pattern: ^accounts/{pk}/$ Name: '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' 参数未指定，并且无法自动确定视图中的名称，因为它没有' .queryset' 属性。

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

使用 include 与路由

路由实例上的 .urls 属性是一个标准的 URL patterns。关于如何包含这些 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)),
]
复制代码

还可以设置 namespace。

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

如果对超链接序列化器使用命名空间，则还需要确保序列化器上的任何 view_name 参数都能正确反映命名空间。在上面的示例中，您需要为超链接到用户详细信息视图的序列化程序字段包含诸如 view_name='api:user-detail' 之类的参数。

额外的链接和操作

用 @detail_route 或 @list_route 装饰的 视图上的任何方法 也将被路由。例如，在 UserViewSet 类中给出这样的方法：

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

class UserViewSet(ModelViewSet):
    ...

    @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf])
    def set_password(self, request, pk=None):
        ...
复制代码

会生成以下URL模式：

• URL pattern: ^users/{pk}/set_password/$ Name: 'user-set-password'

如果您不想使用默认生成的 URL 模式，则可以使用 url_path 参数对其进行自定义。

例如，如果您想将我们的自定义操作的URL更改为 ^users/{pk}/change-password/$，则可以编写：

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

class UserViewSet(ModelViewSet):
    ...

    @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf], url_path='change-password')
    def set_password(self, request, pk=None):
        ...
复制代码

上面的例子现在将生成以下URL模式：

• URL pattern: ^users/{pk}/change-password/$ Name: 'user-change-password'

如果您不想使用生成的默认名称，则可以使用 url_name 参数对其进行自定义。

例如，如果您想将自定义操作的名称更改为 'user-change-password'，则可以编写：

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

class UserViewSet(ModelViewSet):
    ...

    @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf], url_name='change-password')
    def set_password(self, request, pk=None):
        ...
复制代码

上面的例子现在将生成以下URL模式：

• URL pattern: ^users/{pk}/set_password/$ Name: 'user-change-password'

可以同时使用 url_path 和 url_name 参数。

更多相关信息请看 视图集：标记额外的路由行为。

API 参考

SimpleRouter

SimpleRouter 包含标准的 list，create，retrieve，update，partial_update 和 destroy action。SimpleRouter 还支持视图集使用 @detail_route 或 @list_route 装饰器标记其他要路由的方法。

URL Style	HTTP Method	Action	URL Name
{prefix}/	GET	list	{basename}-list
	POST	create
{prefix}/{methodname}/	GET, 或者由 `methods` 参数指定	`@list_route` 装饰的方法	{basename}-{methodname}
{prefix}/{lookup}/	GET	retrieve	{basename}-detail
	PUT	update
	PATCH	partial_update
	DELETE	destroy
{prefix}/{lookup}/{methodname}/	GET, 或者由 `methods` 参数指定	`@detail_route` 装饰的方法	{basename}-{methodname}

默认情况下，由 SimpleRouter 创建的 URL 附加了尾部斜杠。在实例化路由器时，可以通过将 trailing_slash 参数设置为 False 来修改此行为。例如：

router = SimpleRouter(trailing_slash=False)
复制代码

尾部斜杠在 Django 中是常规的，但在其他一些框架（如 Rails）中默认不使用。选择使用哪种风格在很大程度上是一个偏好问题，尽管一些 JavaScript 框架可能会期望特定的路由风格。

SimpleRouter 将匹配包含除斜杠和句点字符以外的任何字符的 lookup 值。对于更严格（或宽松）的 lookup pattern，请在视图集上设置 lookup_value_regex 属性。例如，您可以将 lookup 限制为有效的 UUID：

class MyModelViewSet(mixins.RetrieveModelMixin, viewsets.GenericViewSet):
    lookup_field = 'my_model_id'
    lookup_value_regex = '[0-9a-f]{32}'
复制代码

DefaultRouter

DefaultRouter 与上面的 SimpleRouter 相似，但还包含一个默认的 API 根视图，该视图返回一个包含指向所有列表视图的超链接的响应。它还为可选的 .json 风格格式后缀生成路由。

URL Style	HTTP Method	Action	URL Name
[.format]	GET	自动生成的根视图	api-root
{prefix}/[.format]	GET	list	{basename}-list
	POST	create
{prefix}/{methodname}/[.format]	GET, 或者由 `methods` 参数指定	`@list_route` 装饰的方法	{basename}-{methodname}
{prefix}/{lookup}/[.format]	GET	retrieve	{basename}-detail
	PUT	update
	PATCH	partial_update
	DELETE	destroy
{prefix}/{lookup}/{methodname}/[.format]	GET, 或者由 `methods` 参数指定	`@detail_route` 装饰的方法	{basename}-{methodname}

注意：我在使用 3.7.7 版本时，发现要写成 {prefix}[.format]/ 风格才能访问，{prefix}/[.format] 风格会报 404，不知道是我设置问题还是官方更新了。

与 SimpleRouter 一样，通过在实例化 DefaultRouter 时将 trailing_slash 参数设置为 False，可以删除 URL 路径上的尾部斜杠。

router = DefaultRouter(trailing_slash=False)
复制代码

自定义路由

自定义路由并不是你经常需要做的事情，但是如果你对 API 的 URL 是如何构建的有特定的要求的话，它会很有用。这样做可以让你以可重用的方式封装 URL 结构，确保你不必为每个新视图明确编写 URL 模式。

实现自定义路由的最简单方法是对现有路由类之一进行子类化。.routes 属性用于对将映射到每个视图集的 URL 模式进行模板化。.Routes 属性是一个 Route 列表（Route 的是一个 namedtuple）。

Route 命名元组的参数：

url ： 表示要路由的 URL 的字符串。可以包含以下格式字符串：

• {prefix} - 路由的 URL 前缀。
• {lookup} - 匹配单个实例的 lookup field。
• {trailing_slash} - 可以是 '/' 或空字符串，具体取决于 trailing_slash 参数。

mapping ： HTTP 方法名称与视图方法的映射

name： 用于调用 reverse 时的 URL 的名称。可能包含以下格式字符串：

• {basename} - 创建的 URL 名称的基础。

initkwargs： 实例化视图时应传递的任何其他参数的字典。注意，suffix 参数被保留用于标识视图集类型，在生成视图名称和 breadcrumb 链接时使用。

自定义动态路由

你还可以自定义 @list_route 和 @detail_route 装饰器的路由方式。要路由这两个装饰器中的一个或两个，请在 .routes 列表中包含一个 DynamicListRoute 和/或 DynamicDetailRoute（别忘了类型是 namedtuple）。

DynamicListRoute 和 DynamicDetailRoute 的参数是：

url： 表示要路由的 URL 的字符串。可以包含与 Route 相同的格式字符串，并且还接受 {methodname} 和 {methodnamehyphen} 格式的字符串。

name： 用于调用 reverse 时的名称。可以包含以下格式字符串：{basename} , {methodname} 和 {methodnamehyphen} 。

initkwargs： 实例化视图时应传递的任何其他参数的字典。

举个栗子

以下示例只会路由 list 和 retrieve action，并且不使用尾部斜杠约定。

from rest_framework.routers import Route, DynamicDetailRoute, SimpleRouter

class CustomReadOnlyRouter(SimpleRouter):
    """
    A router for read-only APIs, which doesn't use trailing slashes.
    """
    routes = [
        Route(
            url=r'^{prefix}$',
            mapping={'get': 'list'},
            name='{basename}-list',
            initkwargs={'suffix': 'List'}
        ),
        Route(
            url=r'^{prefix}/{lookup}$',
            mapping={'get': 'retrieve'},
            name='{basename}-detail',
            initkwargs={'suffix': 'Detail'}
        ),
        DynamicDetailRoute(
            url=r'^{prefix}/{lookup}/{methodnamehyphen}$',
            name='{basename}-{methodnamehyphen}',
            initkwargs={}
        )
    ]
复制代码

让我们来看看 CustomReadOnlyRouter 为一个简单的视图集生成的路由。

views.py：

class UserViewSet(viewsets.ReadOnlyModelViewSet):
    """
    A viewset that provides the standard actions
    """
    queryset = User.objects.all()
    serializer_class = UserSerializer
    lookup_field = 'username'

    @detail_route()
    def group_names(self, request, pk=None):
        """
        Returns a list of all the group names that the given
        user belongs to.
        """
        user = self.get_object()
        groups = user.groups.all()
        return Response([group.name for group in groups])
复制代码

urls.py：

router = CustomReadOnlyRouter()
router.register('users', UserViewSet)
urlpatterns = router.urls
复制代码

将生成以下映射...

URL	HTTP Method	Action	URL Name
/users	GET	list	user-list
/users/{username}	GET	retrieve	user-detail
/users/{username}/group-names	GET	group_names	user-group-names

有关设置 .routes 属性的另一个示例，请参阅 SimpleRouter 类的源代码。

自定义路由器进阶

如果想提供完全自定义的行为，可以继承 BaseRouter 并覆盖 get_urls(self) 方法。该方法应检查已注册的视图集并返回一组 URL 模式。可以通过访问 self.registry 属性来检查注册的 prefix，viewset 和 basename tuples。

你可能还想覆盖 get_default_base_name（self，viewset）方法，或者在向路由注册视图集时始终显式设置 base_name 参数。

第三方软件包

以下是可用的第三方包。

DRF Nested Routers

ModelRouter (wq.db.rest)

DRF-extensions