Django Rest Framework 三种分页配置详解：PageNumber、LimitOffset 与 Cursor

叶初

发布时间：2026-10-13| 5人浏览过

原创

本文详解 Django Rest Framework 中的三种分页实现方式。通过全局配置与视图级配置，分别演示 PageNumberPagination（页码分页）、LimitOffsetPagination（偏移量分页）及 CursorPagination（加密游标分页）的具体用法。涵盖序列化类定义、分页器参数配置及 API 测试示例，帮助开发者高效处理大数据量展示。

DRF 分页机制概述与全局配置

前言

当数据库中存储了数千万条数据时，直接全量读取会引发严重的内存压力，甚至导致内存溢出。因此，我们需要采用分批读取的策略，以减轻系统负担。

在前端展示层面，同样需要对数据进行分页处理，以提升用户体验和加载效率。

本文将深入解析 DRF（Django Rest Framework）提供的三种主流分页机制及其配置方法。

全局配置


REST_FRAMEWORK = {
  # 对所有分页器生效，但优先级低
  'PAGE_SIZE': 5, # 每页显示5条数据
}

首先，我们需要准备用于测试分页的数据模型以及对应的序列化类。


from django.db import models

class Test(models.Model):
  """用于测试分页的数据表"""
  name = models.CharField(max_length=64)

接下来，生成用于测试的数据记录。


# 在Python脚本中调用Django环境
import os

if __name__ == '__main__':
  # 将下面的'blog095.settings'改为项目对应的名称后直接执行即可生成记录
  os.environ.setdefault('DJANGO_SETTINGS_MODULE', > 'blog095.settings')
  import django
  django.setup()
  from blog.models import Test # 导入数据表
  [Test.objects.create(name="花千骨%s" % str(i)) for i in range(100)]

定义用于测试数据的序列化类。


from rest_framework.serializers import ModelSerializer
from blog.models import Test # 导入数据表

class TestSerializer(ModelSerializer):
  """用于测试分页的序列化类"""
  class Meta:
    model = Test
    fields = '__all__'

第一种方式：PageNumberPagination（页码分页）。该方式允许用户指定查询第 n 页，并设定每页显示的数据条数。

第一步：配置分页器类。

PageNumberPagination 页码分页实现


from rest_framework import pagination

class PageNumberPagination(pagination.PageNumberPagination):
  """查第n页，每页显示n条数据"""
  page_size = 10 # 指定每页显示多少条数据
  page_size_query_param = 'size' # URL参数中每页显示条数的参数
  page_query_param = 'page' # URL中页码的参数
  max_page_size = None # 每页最多显示多少条数据

第二步：在视图文件中应用该分页器。


from rest_framework.response import Response
from rest_framework.views import APIView
from rest_framework.serializers import ModelSerializer
from blog.models import Test # 导入数据表
from blog import pagination # 导入上面的分页配置

class Test01View(APIView):
  def get(self, request):
    queryset = Test.objects.all()

    # 1. 实例化分页器对象
    page_obj = pagination.PageNumberPagination()

    # 2. 使用自己配置的分页器调用分页方法进行分页
    page_data = page_obj.paginate_queryset(queryset, request)

    # 3. 序列化我们分页好的数据
    ser_obj = TestSerializer(page_data, many=True)

    # # 4. 返回数据
    # return Response(ser_obj.data)

    # 4. 返回带上一页/下一页连接的页面
    return page_obj.get_paginated_response(ser_obj.data)

第三步：进行访问测试。

如上图所示，当指定 page=10 且 size=5 时，接口返回了相应的分页数据。

第二种方式：LimitOffsetPagination（偏移量分页）。该方式允许指定从第 n 个位置开始，向后查询 n 条数据。

第一步：配置分页器类。

LimitOffsetPagination 偏移量分页实现


from rest_framework import pagination

class LimitOffsetPagination(pagination.LimitOffsetPagination):
  """在第n个位置，向后查n条数据"""
  default_limit = 1 # 指定默认查多少条数据
  limit_query_param = 'limit' # URL中指定查多少条数据的参数
  offset_query_param = 'offset' # URL中指定从第几条数据开始查的参数
  max_limit = 999 # 最大显示多少条数据

第二步：在视图文件中应用该分页器。


from rest_framework.response import Response
from rest_framework.views import APIView
from rest_framework.serializers import ModelSerializer
from blog.models import Test # 导入数据表
from blog.pagination import LimitOffsetPagination # 导入上面的分页配置


class Test02View(APIView):
  def get(self, request):
    queryset = Test.objects.all()

    # 1. 实例化分页器对象
    page_obj = LimitOffsetPagination()

    # 2. 使用自己配置的分页器调用分页方法进行分页
    page_data = page_obj.paginate_queryset(queryset, request)

    # 3. 序列化我们分页好的数据
    ser_obj = TestSerializer(page_data, many=True)

    # # 4. 返回数据
    # return Response(ser_obj.data)

    # 4. 返回带上一页/下一页连接的页面
    return page_obj.get_paginated_response(ser_obj.data)

第三步：进行访问测试。

***

第三种方式：CursorPagination（加密游标分页）。这是一种基于加密游标的分页机制，适用于大数据量且对性能要求较高的场景。

第一步：配置分页器类。

CursorPagination 加密游标分页实现


from rest_framework import pagination

class CursorPagination(pagination.CursorPagination):
  """加密游标的分页"""
  cursor_query_param = 'cursor' # 游标(这是加密的游标)
  # ordering = '-id' # 从后往前取数据
  ordering = 'id'
  page_size = 1 # 每页显示的条数

第二步：在视图文件中应用该分页器。


from rest_framework.response import Response
from rest_framework.views import APIView
from rest_framework.serializers import ModelSerializer
from blog.models import Test # 导入数据表
from blog.pagination import CursorPagination # 导入上面的分页配置

class Test03View(APIView):
  def get(self, request):
    queryset = Test.objects.all()

    # 1. 实例化分页器对象
    page_obj = CursorPagination()

    # 2. 使用自己配置的分页器调用分页方法进行分页
    page_data = page_obj.paginate_queryset(queryset, request)

    # 3. 序列化我们分页好的数据
    ser_obj = TestSerializer(page_data, many=True)

    # # 4. 返回数据
    # return Response(ser_obj.data)

    # 4. 返回带上一页/下一页连接的页面
    return page_obj.get_paginated_response(ser_obj.data)

完成配置后，即可通过浏览器或客户端工具进行功能测试。

此外，DRF 的视图系统还支持生成带有上一页/下一页导航按钮的页面结构。

ModelViewSet 中的分页配置与导航


from rest_framework.viewsets import ModelViewSet

class Test04View(ModelViewSet):
  queryset = Test.objects.all()
  serializer_class = TestSerializer
  pagination_class = CursorPagination # 指定分页配置器

具体效果如下图所示。