📦 Django DRF 中如何手动调用分页器返回分页数据（APIView，action场景）

在使用 Django REST Framework（DRF）时，很多人习惯了用 GenericAPIView 或 ViewSet 自动帮我们处理分页。但在某些场景中，例如使用原始的 APIView，你就需要 手动调用分页器 来返回分页数据。

如果你也遇到以下问题：

• ❓为什么我的 APIView 不分页？
• ❓我能不能在普通的 APIView 里也使用 DRF 的分页？
• ❓如何返回 count、next、previous 等结构？

本文将带你一步步搞定！

---

🎯 目标

我们将实现这样一个接口：

GET /api/books/?page=2&page_size=5

返回内容：

{
  "count": 42,
  "next": "http://api.example.com/api/books/?page=3&page_size=5",
  "previous": "http://api.example.com/api/books/?page=1&page_size=5",
  "results": [
    { "id": 6, "title": "第6本书" },
    { "id": 7, "title": "第7本书" }
  ]
}

---

⚙️ 一、为什么 APIView 不会自动分页？

因为分页逻辑默认写在 GenericAPIView 里，而 APIView 是最基础的类，不会自动处理分页、过滤、排序等操作。

所以我们需要 手动创建分页器 + 手动调用两个方法：

• paginate_queryset(queryset, request)：返回当前页数据
• get_paginated_response(data)：返回统一格式响应

---

🛠️ 二、完整示例代码

假设我们有一个 Book 模型和对应的序列化器：

# models.py
class Book(models.Model):
    title = models.CharField(max_length=100)
# serializers.py
class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ['id', 'title']

接下来，在视图中手动分页：

# views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.pagination import PageNumberPagination
from .models import Book
from .serializers import BookSerializer

class BookListView(APIView):
    def get(self, request):
        queryset = Book.objects.all().order_by('id')

        # 1. 创建分页器对象
        paginator = PageNumberPagination()
        paginator.page_size = 10  # 每页数量（可配置）

        # 2. 手动分页
        page = paginator.paginate_queryset(queryset, request)

        # 3. 序列化当前页数据
        serializer = BookSerializer(page, many=True)

        # 4. 返回分页响应
        return paginator.get_paginated_response(serializer.data)

---

🧰 三、支持 URL 参数控制分页

你可以通过以下方式控制分页：

GET /api/books/?page=2&page_size=5

• page：页码
• page_size：每页条数（需要设置 page_size_query_param）

想支持自定义 page_size？给分页器加一行：

paginator.page_size_query_param = 'page_size'

---

✨ 四、进阶：自定义返回结构

默认返回结构长这样：

{
  "count": 42,
  "next": "...",
  "previous": "...",
  "results": [...]
}

如果你想自定义成更“业务风格”的结构，例如：

{
  "code": 0,
  "message": "ok",
  "data": {
    "total": 42,
    "page": 2,
    "page_size": 10,
    "list": [...]
  }
}

可以自定义分页类：

from rest_framework.pagination import PageNumberPagination
from rest_framework.response import Response

class CustomPagination(PageNumberPagination):
    page_size_query_param = 'page_size'

    def get_paginated_response(self, data):
        return Response({
            "code": 0,
            "message": "ok",
            "data": {
                "total": self.page.paginator.count,
                "page": self.page.number,
                "page_size": self.page.paginator.per_page,
                "list": data
            }
        })

然后在视图中使用：

paginator = CustomPagination()

---

✅ 总结

步骤	方法	说明
①	创建分页器实例	paginator = PageNumberPagination()
②	分页数据	page = paginator.paginate_queryset(queryset, request)
③	序列化数据	serializer = YourSerializer(page, many=True)
④	返回响应	return paginator.get_paginated_response(serializer.data)

---

🧠 最后一句话：

即使你用的是最基础的 APIView，也可以优雅地分页 —— 手动调用分页器，就是打开分页大门的钥匙。

---