Django REST Framework报错：无法解析user-detail视图名称的URL关联

我正在学习Django REST Framework教程，groups接口可正常运行，但users接口出现异常。错误信息如下：

ImproperlyConfigured at /polls/users/
Could not resolve URL for hyperlinked relationship using view name "user-detail". You may have failed to include the related model in your API, or incorrectly configured the lookup_field attribute on this field.

相关代码 #

Serializers代码 #

from django.contrib.auth.models import User, Group
from rest_framework import serializers


class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ['url', 'username', 'email', 'groups']


class GroupSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Group
        fields = ['url', 'name']

Views代码 #

from django.contrib.auth.models import User, Group
from rest_framework import viewsets
from rest_framework import permissions
from .serializers import UserSerializer, GroupSerializer

class UserViewSet(viewsets.ModelViewSet):
    """ API endpoint that allows users to be viewed or edited """
    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer
    permission_classes = [permissions.IsAuthenticated]


class GroupViewSet(viewsets.ModelViewSet):
    """ API endpoint that allows groups to be viewed or edited """
    queryset = Group.objects.all()
    serializer_class = GroupSerializer
    permission_classes = [permissions.IsAuthenticated]

Urls代码 #

from django.urls import path, include
from . import views
from rest_framework import routers

# for rest framework
router = routers.DefaultRouter()
router.register(r'users', views.UserViewSet)
router.register(r'groups', views.GroupViewSet)

urlpatterns = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

底层原因分析 #

这个错误的核心是HyperlinkedModelSerializer依赖视图名称反向生成超链接，但URL配置的命名空间或应用名称设置不匹配，导致无法找到对应的视图，具体分两种常见场景：

场景1：URL包含时使用了namespace但未设置app_name #

如果你的项目主urls.py中，将polls应用的URL通过namespace参数包含（示例如下）：

# 主urls.py
path('polls/', include('polls.urls', namespace='polls'))

但在polls的urls.py中没有声明app_name = 'polls'，Django会无法正确关联命名空间与应用内的视图，导致user-detail这类视图名称无法被解析（实际应该是polls:user-detail，但序列化器默认查找不带命名空间的名称）。

场景2：序列化器未适配带命名空间的视图名称 #

当URL配置带有命名空间时，HyperlinkedModelSerializer生成的超链接字段（包括User的url字段和groups关联字段）默认使用不带命名空间的视图名称（如user-detail、group-detail）进行反向解析，而实际的视图名称已经带上了命名空间前缀（如polls:user-detail），两者不匹配导致解析失败。

Groups接口正常的原因 #

Groups接口的GroupSerializer仅包含自身的url字段和name字段，没有关联其他模型。如果Groups接口正常，大概率是因为在序列化Group列表时，其url字段的视图名称解析刚好没有触发冲突（或者你测试Groups时没有触发到需要解析其他视图名称的场景），但本质上如果命名空间问题存在，Groups接口的详情页超链接也会有潜在问题。

内容的提问来源于stack exchange，提问作者Sura Amilbahar