Django REST Framework中ModelViewSet的pagination_class被忽略问题求助

问题描述 #

我在Django REST Framework里实现了一个ModelViewSet用于返回Order对象列表，为了优化性能想自定义分页规则，限制每页最多返回65条数据。但我明明已经在ViewSet上显式指定了自定义分页类，API接口却依旧返回全部300+条未分页的结果，完全没用到我的自定义分页配置。

我的目标是：当请求.../api/orders/?page=1时，接口返回标准的DRF分页响应结构，包含count（总条数）、next（下一页链接）、previous（上一页链接）和results（当前页最多65条数据列表）。

我尝试的配置步骤 #

1. 自定义分页类（my_app/pagination.py） #

我继承了PageNumberPagination实现了自定义分页规则：

# my_app/pagination.py
from rest_framework.pagination import PageNumberPagination

class CustomOrderPagination(PageNumberPagination):
    page_size = 65  # 默认每页65条
    page_size_query_param = 'page_size'  # 允许客户端通过参数自定义每页条数
    max_page_size = 100  # 客户端自定义的最大每页条数限制

2. 视图绑定分页类（my_app/views.py） #

在ModelViewSet里直接指定了pagination_class，同时为了性能优化，查询集用了select_related和prefetch_related做关联查询，还加了annotate计算聚合字段：

# my_app/views.py
from rest_framework import viewsets
from django.db.models import Sum
from .models import Order
from .serializers import OrderSlimSerializer
from .pagination import CustomOrderPagination

class OrderViewSet(viewsets.ModelViewSet):
    # 显式绑定自定义分页类
    pagination_class = CustomOrderPagination
    serializer_class = OrderSlimSerializer
    queryset = Order.objects.select_related('client').prefetch_related(
        'orderitem_set__location__service_plan'
    ).annotate(
        total_amount=Sum('orderitem_set__service_plan__service_fee')
    )
    # ... 其他配置：permission_classes、filter_backends等 ...

3. 精简序列化器（my_app/serializers.py） #

为了缩小响应体积，用了精简的序列化器：

# my_app/serializers.py
from rest_framework import serializers
from .models import OrderItem, Order

class LocationItemSerializer(serializers.ModelSerializer):
    # ... 仅返回Location的必要字段 ...
    class Meta:
        model = OrderItem
        fields = ['location_name', 'service_plan_details']

class OrderSlimSerializer(serializers.ModelSerializer):
    client_name = serializers.CharField(source='client.name')
    locations = LocationItemSerializer(source='orderitem_set', many=True)
    charge_amount = serializers.DecimalField(source='total_amount', read_only=True)
    
    class Meta:
        model = Order
        fields = ['id', 'order_number', 'client_name', 'locations', 'charge_amount']

4. 请求测试 #

我用curl带page参数请求接口：

curl "http://localhost:8000/api/orders/?page=1"

5. 全局DRF配置（settings.py） #

全局配置里也设置了默认分页，确保没有全局禁用分页：

REST_FRAMEWORK = {
    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
    "PAGE_SIZE": 100,
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework.authentication.BasicAuthentication",
        "rest_framework.authentication.SessionAuthentication",
        "rest_framework.authentication.TokenAuthentication",
        "rest_framework_simplejwt.authentication.JWTAuthentication",
    ],
}

当前异常结果 #

接口返回的是一个包含300+个Order对象的纯数组，完全没有预期的分页结构（比如{"count": 368, "next": null, "previous": null, "results": [...]}）。

我的疑问 #

• 为什么ViewSet上显式设置的pagination_class会被忽略？
• 正确的自定义分页配置方式应该是怎样的？
• 有没有什么全局设置或者代码细节可能会完全禁用分页？

另外我也查过相关问题，但那个是针对普通ViewSet的，不是ModelViewSet，不确定怎么适配我的场景。

可能的排查方向与解决办法 #

我帮你整理几个常见的排查点，按优先级从高到低：

1. 检查是否重写了list方法且未处理分页

如果你的OrderViewSet里重写了list方法，一定要记得手动调用DRF的分页逻辑！ModelViewSet默认的list方法会自动处理分页，但自定义list方法时需要自己实现：

def list(self, request, *args, **kwargs):
    queryset = self.filter_queryset(self.get_queryset())
    
    # 关键：手动触发分页
    page = self.paginate_queryset(queryset)
    if page is not None:
        serializer = self.get_serializer(page, many=True)
        return self.get_paginated_response(serializer.data)
    
    # 未分页的 fallback 逻辑
    serializer = self.get_serializer(queryset, many=True)
    return Response(serializer.data)

如果没重写list方法，跳过这个点。

2. 检查get_queryset是否返回了列表而非QuerySet

如果你重写了get_queryset方法，绝对不能把QuerySet转成列表（比如用list()包裹），因为DRF的分页只对QuerySet生效：

# ❌ 错误示例：返回列表会导致分页失效
def get_queryset(self):
    return list(Order.objects.select_related('client').all())

# ✅ 正确写法：返回原生QuerySet
def get_queryset(self):
    return Order.objects.select_related('client').all()

你的代码里是直接赋值queryset属性，这没问题，但如果有自定义get_queryset一定要注意这点。

3. 排查过滤器后端或权限类的冲突

某些第三方过滤器后端可能会意外修改查询集，导致分页失效。可以临时注释掉filter_backends配置，测试分页是否恢复正常，以此排除过滤器的影响。

4. 验证分页类是否被正确导入

在OrderViewSet里加个调试打印，确认分页类是否被正确加载：

class OrderViewSet(viewsets.ModelViewSet):
    pagination_class = CustomOrderPagination
    # 启动服务时看控制台输出
    print(f"当前使用的分页类: {pagination_class}")
    # ... 其他配置 ...

如果打印的不是my_app.pagination.CustomOrderPagination，说明导入路径写错了，检查from .pagination import CustomOrderPagination的拼写和文件路径。

5. 用极简ViewSet做隔离测试

创建一个极简的测试ViewSet，排除其他配置干扰：

# 在views.py里新增测试视图
class TestOrderViewSet(viewsets.ModelViewSet):
    pagination_class = CustomOrderPagination
    serializer_class = OrderSlimSerializer
    queryset = Order.objects.all()

在urls.py里配置单独的路由：

path('api/test-orders/', TestOrderViewSet.as_view({'get': 'list'})),

请求/api/test-orders/?page=1，如果这个测试接口分页正常，说明原ViewSet的queryset（比如annotate、prefetch_related）或其他配置导致了问题，再逐步把原配置加回去排查。

6. 检查DRF版本兼容性

如果用的是比较旧的DRF版本，可能存在ModelViewSet分页的bug。可以先把全局PAGE_SIZE改成65，测试全局分页是否生效：如果全局生效但局部配置不生效，说明局部配置的优先级被意外覆盖了，检查是否有父类ViewSet或装饰器（比如@pagination_class(...)）覆盖了你的类属性。

内容来源于stack exchange