PageNumberPagination适合页码跳转场景,LimitOffsetPagination适配LIMIT/OFFSET语义;视图级pagination_class优先级高于全局配置;自定义get_paginated_response需保留results、count、next、previous字段;queryset必须保持惰性求值,提前转list会导致分页失效。

分页类怎么选:PageNumberPagination vs LimitOffsetPagination
Django REST framework 提供了几个内置分页类,最常用的是 PageNumberPagination 和 LimitOffsetPagination。前者适合「第几页」这种用户友好型场景(比如前端带页码跳转),后者更接近数据库的 LIMIT/OFFSET 语义,适合 API 客户端自己控制偏移量。
选错会导致行为不符合预期:比如用 PageNumberPagination 却没传 page 参数,会默认返回第 1 页;而 LimitOffsetPagination 没传 limit 就直接报错 "limit" is required。
-
PageNumberPagination:需配置page_size和可选的page_query_param(默认"page") -
LimitOffsetPagination:需配置default_limit,limit_query_param默认是"limit",offset_query_param默认是"offset" - 如果接口要支持游标分页(避免深度翻页性能退化),得用
CursorPagination,但它要求 queryset 有唯一、单调递增/递减字段(如id或created_at),且不支持随机跳页
全局配置 vs 视图级覆盖:哪个优先级更高?
DRF 的分页行为由视图的 pagination_class 属性决定,它会覆盖全局设置。也就是说,即使你在 settings.py 里写了 REST_FRAMEWORK = {"DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination", "PAGE_SIZE": 20},只要某个 APIView 或 ModelViewSet 显式设了 pagination_class = None,那这个视图就完全不分页。
常见误操作是只改了全局 PAGE_SIZE,但忘了某些视图继承自 GenericAPIView 并自定义了 pagination_class,结果改了 settings 却没生效。
立即学习“Python免费学习笔记(深入)”;
- 全局配置适合统一规范,但无法满足所有接口需求(比如列表页要分页,导出接口不能分页)
- 视图级设置优先级更高,推荐在
ModelViewSet中按需覆盖:pagination_class = LargeResultsSetPagination - 想临时禁用分页?直接设
pagination_class = None,别用空列表或False,那会报错
自定义分页类时,get_paginated_response 怎么改才不丢数据?
很多同学继承 PageNumberPagination 后只重写了 page_size,却在覆写 get_paginated_response() 时漏掉关键字段,导致前端收不到 count 或 next/previous 链接。
这个方法返回的是 Response 对象,必须包含至少 results(数据列表)、count(总条数)、next 和 previous(分页链接)。DRF 默认实现已经处理了 URL 构造和参数透传,自己写时别硬拼字符串——用 self.get_next_link() 和 self.get_previous_link() 更安全。
- 错误示例:
return Response({"data": data})→ 前端拿不到分页元信息 - 正确做法:调用父类逻辑再包一层,例如:
response = super().get_paginated_response(data); response.data["status"] = "success" - 注意:修改
response.data是安全的,但不要替换整个response.data字典,否则会丢掉 DRF 自动注入的分页字段
queryset 被提前求值后,分页会失效
这是个隐蔽但高频的问题:如果你在视图的 get_queryset() 里写了 return list(MyModel.objects.all()) 或用了 .values()/.values_list() 后又转成 list,那分页器拿到的就是 Python 列表,不是 QuerySet,paginator.paginate_queryset() 会直接报错 "'list' object has no attribute 'all'" 或静默失败(返回全部数据但不提示)。
分页器依赖 QuerySet 的惰性求值特性,只有在真正需要切片时才执行 SQL。一旦被转成 list、tuple、dict 或遍历过(比如 for 循环),分页就断掉了。
- 检查点:所有
get_queryset()方法结尾必须返回未求值的 QuerySet - 过滤逻辑可以链式调用:
qs.filter(...).select_related(...),没问题 - 避免在分页前做
qs.count()或len(qs),这会触发一次全表扫描,影响性能


















