Django Rest Framework源碼剖析(七)-----分頁

分頁對於大多數網站來說是必不可少的，那你使用restful架構時候，你可以從後臺獲取數據，在前端利用利用框架或自定義分頁，這是一種解決方案。當然django rest framework提供了分頁組件，讓我們可以更靈活的進行分頁。 django rest framework提供了三種分頁組件： Pa ...

一、簡介

分頁對於大多數網站來說是必不可少的，那你使用restful架構時候，你可以從後臺獲取數據，在前端利用利用框架或自定義分頁，這是一種解決方案。當然django rest framework提供了分頁組件，讓我們可以更靈活的進行分頁。

django rest framework提供了三種分頁組件：

PageNumberPagination：普通分頁，查看第n頁，每個頁面顯示n條數據
LimitOffsetPagination：基於位置的分頁，在第n個位置，向後查看n條數據，和資料庫的sql語句中的limit offset類似，參數offet代表位置，limit代表取多少條數據。
CursorPagination：游標分頁，意思就是每次返回當前頁、上一頁、下一頁，並且每次的上一頁和下一頁的url是不規則的

二、每個分頁組件使用

這裡我們使用之前的模型，如果沒有在setting中註冊django rest framework 請註冊它，為了方便我們查看分頁，配置項在INSTALLED_APPS：

1.PageNumberPagination類分頁

settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'app01.apps.App01Config',
    'rest_framework',  #註冊DRF
]

models.py

from django.db import models

class UserInfo(models.Model):
    user_type_choice = (
        (1,"普通用戶"),
        (2,"會員"),
    )
    user_type = models.IntegerField(choices=user_type_choice)
    username = models.CharField(max_length=32,unique=True)
    password = models.CharField(max_length=64)
    group = models.ForeignKey(to='UserGroup',null=True,blank=True)
    roles = models.ManyToManyField(to='Role')


class UserToken(models.Model):
    user = models.OneToOneField(to=UserInfo)
    token = models.CharField(max_length=64)



class UserGroup(models.Model):
    """用戶組"""
    name = models.CharField(max_length=32,unique=True)


class Role(models.Model):
    """角色"""
    name = models.CharField(max_length=32,unique=True)

urls.py

urlpatterns = [

    # url(r'^api/v1/auth', views.AuthView.as_view()),
    # url(r'^api/v1/order', views.OrderView.as_view()),
    url(r'^api/v1/roles', views.RoleView.as_view()),   #分頁示例1
    url(r'^api/v1/userinfo', views.UserinfoView.as_view()),
    url(r'^api/v1/group/(?P<xxx>\d+)', views.GroupView.as_view(),name='gp'),
    # url(r'^api/(?P<version>[v1|v2]+)/user', views.UserView.as_view(),name="user_view"),
]

本次我們使用roles來作為示例，並且為了更好的顯示，此次會用到django rest framework 的響應（Response），後續會介紹，下麵是對角色視圖的序列化，這個已經在前面的序列化篇章中說明如下：

from rest_framework import serializers
from rest_framework.response import Response   #使用DRF自帶的響應頁面更美觀
class RolesSerializer(serializers.Serializer): #定義序列化類
    id=serializers.IntegerField()  #定義需要提取的序列化欄位,名稱和model中定義的欄位相同
    name=serializers.CharField()
class RoleView(APIView):
    """角色"""
    def get(self,request,*args,**kwargs):
        roles=models.Role.objects.all()
        res=RolesSerializer(instance=roles,many=True) #instance接受queryset對象或者單個model對象，當有多條數據時候，使用many=True,單個對象many=False
        return Response(res.data)

訪問：http://127.0.0.1:8000/api/v1/roles，顯示出所有的角色，如下：

加入分頁後的角色視圖：

from rest_framework import serializers
from rest_framework.response import Response   #使用DRF自帶的響應頁面更美觀
from rest_framework.pagination import PageNumberPagination
class RolesSerializer(serializers.Serializer): #定義序列化類
    id=serializers.IntegerField()  #定義需要提取的序列化欄位,名稱和model中定義的欄位相同
    name=serializers.CharField()
class RoleView(APIView):
    """角色"""
    def get(self,request,*args,**kwargs):
        roles=models.Role.objects.all() # 獲取所有數據

        pg_obj=PageNumberPagination()  # 實例化分頁類
        pg_res=pg_obj.paginate_queryset(queryset=roles,request=request,view=self)
        # 獲取分頁數據，參數一 分頁的數據，QuerySet類型，請求request,分頁的視圖，self代表自己
        res=RolesSerializer(instance=pg_res,many=True)  # 對分完頁碼的數據進行序列化
        return Response(res.data)

同時，我們還需要配置每頁顯示的數據條數，在settings.py中：

REST_FRAMEWORK = {
    "DEFAULT_PARSER_CLASSES": ["rest_framework.parsers.JSONParser", "rest_framework.parsers.JSONParser"],# 全局解析器配置
    "PAGE_SIZE":2,#配置每頁顯示多少條數據
}

此時我們訪問：http://127.0.0.1:8000/api/v1/roles?page=1，則顯示第一頁，訪問http://127.0.0.1:8000/api/v1/roles?page=2則顯示第二頁，如下圖：

但是一般情況我們需要自己定義分頁類，來定製更多的功能，示例：

自定義分頁，更多的定製功能：

from rest_framework import serializers
from rest_framework.response import Response   #使用DRF自帶的響應頁面更美觀
from rest_framework.pagination import PageNumberPagination

class Mypagination(PageNumberPagination):
    """自定義分頁"""
    page_size=2  #預設每頁顯示個數配置
    page_query_param = 'p' # 頁面傳參的key,預設是page
    page_size_query_param='size'  # 指定每頁顯示個數參數
    max_page_size=4 # 每頁最多顯示個數配置，使用以上配置，可以支持每頁可顯示2~4條數據

class RolesSerializer(serializers.Serializer): #定義序列化類
    id=serializers.IntegerField()  #定義需要提取的序列化欄位,名稱和model中定義的欄位相同
    name=serializers.CharField()
class RoleView(APIView):
    """角色"""
    def get(self,request,*args,**kwargs):
        roles=models.Role.objects.all() # 獲取所有數據

        pg_obj=Mypagination()  # 實例化分頁類
        pg_res=pg_obj.paginate_queryset(queryset=roles,request=request,view=self)
        # 獲取分頁數據，參數一 分頁的數據，QuerySet類型，請求request,分頁的視圖，self代表自己
        res=RolesSerializer(instance=pg_res,many=True)  # 對分完頁碼的數據進行序列化
        return Response(res.data)

訪問：http://127.0.0.1:8000/api/v1/roles?p=1&size=3，需要註意的是此時的分頁參數已經重寫，查看結果：

from rest_framework import serializers
from rest_framework.response import Response   #使用DRF自帶的響應頁面更美觀
from rest_framework.pagination import PageNumberPagination

class Mypagination(PageNumberPagination):
    """自定義分頁"""
    page_size=2  #預設每頁顯示個數配置
    page_query_param = 'p' # 頁面傳參的key,預設是page
    page_size_query_param='size'  # 指定每頁顯示個數參數
    max_page_size=4 # 每頁最多顯示個數配置，使用以上配置，可以支持每頁可顯示2~4條數據

class RolesSerializer(serializers.Serializer): #定義序列化類
    id=serializers.IntegerField()  #定義需要提取的序列化欄位,名稱和model中定義的欄位相同
    name=serializers.CharField()
class RoleView(APIView):
    """角色"""
    def get(self,request,*args,**kwargs):
        roles=models.Role.objects.all() # 獲取所有數據

        pg_obj=Mypagination()  # 實例化分頁類
        pg_res=pg_obj.paginate_queryset(queryset=roles,request=request,view=self)
        # 獲取分頁數據，參數一 分頁的數據，QuerySet類型，請求request,分頁的視圖，self代表自己
        res=RolesSerializer(instance=pg_res,many=True)  # 對分完頁碼的數據進行序列化
        return pg_obj.get_paginated_response(res.data)   # 使用分頁自帶的respose返回，具有上一頁下一頁功能

2.LimitOffsetPagination類分頁

同樣我們以角色視圖做示例，通過自定義實現分頁，示例：

from rest_framework import serializers
from rest_framework.response import Response   #使用DRF自帶的響應頁面更美觀
from rest_framework.pagination import PageNumberPagination,LimitOffsetPagination

class MyLimitOffsetPagination(LimitOffsetPagination):

    default_limit = 2 #預設顯示的個數
    offset_query_param = "offset" #指定url中位置key值，其位置從0開始
    limit_query_param = "limit"  # 指定url中的偏移個數（顯示個數）的key值
    max_limit = 10  #最多顯示（偏移）的個數

class RolesSerializer(serializers.Serializer): #定義序列化類
    id=serializers.IntegerField()  #定義需要提取的序列化欄位,名稱和model中定義的欄位相同
    name=serializers.CharField()
class RoleView(APIView):
    """角色"""
    def get(self,request,*args,**kwargs):
        roles=models.Role.objects.all() # 獲取所有數據

        pg_obj=MyLimitOffsetPagination() # 實例化分頁類
        pg_res=pg_obj.paginate_queryset(queryset=roles,request=request,view=self)
        # 獲取分頁數據，參數一 分頁的數據，QuerySet類型，請求request,分頁的視圖，self代表自己
        res=RolesSerializer(instance=pg_res,many=True)  # 對分完頁碼的數據進行序列化
        return Response(res.data)

訪問：http://127.0.0.1:8000/api/v1/roles?offset=1&limit=4（從第2個位置開始，查看4條數據），結果如下：

3.CursorPagination類實現分頁（很少用）

示例：

from rest_framework import serializers
from rest_framework.response import Response   #使用DRF自帶的響應頁面更美觀
from rest_framework.pagination import PageNumberPagination,LimitOffsetPagination,CursorPagination

class MyCursorPagination(CursorPagination):
    cursor_query_param = "cursor"  #url獲取分頁的key
    page_size = 2     #每頁顯示2個數據
    ordering = 'id'   #排序規則
    page_size_query_param = 'size' #每頁顯示多少條參數配置
    max_page_size = 5    #每頁最多顯示多少條數據
class RolesSerializer(serializers.Serializer): #定義序列化類
    id=serializers.IntegerField()  #定義需要提取的序列化欄位,名稱和model中定義的欄位相同
    name=serializers.CharField()
class RoleView(APIView):
    """角色"""
    def get(self,request,*args,**kwargs):
        roles=models.Role.objects.all() # 獲取所有數據

        pg_obj=MyCursorPagination() # 實例化分頁類
        pg_res=pg_obj.paginate_queryset(queryset=roles,request=request,view=self)
        # 獲取分頁數據，參數一 分頁的數據，QuerySet類型，請求request,分頁的視圖，self代表自己
        res=RolesSerializer(instance=pg_res,many=True)  # 對分完頁碼的數據進行序列化
        return pg_obj.get_paginated_response(res.data)

訪問http://127.0.0.1:8000/api/v1/roles，結果如下，從結果中可以看到下一頁的url並不規則：

三、源碼剖析

對於以上示例，你可以會有疑問，問什麼配置上了一些類的屬性就能有不同的效果呢？當然源碼是有這些定製配置的，這裡以PageNumberPagination分頁進行說明，下麵是PageNumberPagination的源碼，可能稍微長，我們進行配置部分解讀就好，其他部分和分頁相關的邏輯這裡就不過多介紹，解讀部分請看註釋：

class PageNumberPagination(BasePagination):
    """
    A simple page number based style that supports page numbers as
    query parameters. For example:

    http://api.example.org/accounts/?page=4
    http://api.example.org/accounts/?page=4&page_size=100
    """
    # The default page size.
    # Defaults to `None`, meaning pagination is disabled.
    page_size = api_settings.PAGE_SIZE  #每頁顯示個數配置，可以在setting中配置，也可以在類里，當前類>全局（settings）

    django_paginator_class = DjangoPaginator  # 本質使用django自帶的分頁組件

    # Client can control the page using this query parameter.
    page_query_param = 'page'                # url中的頁碼key配置
    page_query_description = _('A page number within the paginated result set.')    # 描述

    # Client can control the page size using this query parameter.
    # Default is 'None'. Set to eg 'page_size' to enable usage.
    page_size_query_param = None       # url中每頁顯示個數的key配置
    page_size_query_description = _('Number of results to return per page.')

    # Set to an integer to limit the maximum page size the client may request.
    # Only relevant if 'page_size_query_param' has also been set.
    max_page_size = None                 # 最多顯示個數配置

    last_page_strings = ('last',)

    template = 'rest_framework/pagination/numbers.html'   # 渲染的模板

    invalid_page_message = _('Invalid page.')             # 頁面不合法返回的信息，當然我們也可以自己定製

    def paginate_queryset(self, queryset, request, view=None):  # 獲取分頁數據
        """
        Paginate a queryset if required, either returning a
        page object, or `None` if pagination is not configured for this view.
        """
        page_size = self.get_page_size(request)           # 調用get_page_size 獲取當前請求的每頁顯示數量
        if not page_size:
            return None

        paginator = self.django_paginator_class(queryset, page_size)
        page_number = request.query_params.get(self.page_query_param, 1)
        if page_number in self.last_page_strings:
            page_number = paginator.num_pages

        try:
            self.page = paginator.page(page_number)
        except InvalidPage as exc:
            msg = self.invalid_page_message.format(
                page_number=page_number, message=six.text_type(exc)
            )
            raise NotFound(msg)

        if paginator.num_pages > 1 and self.template is not None:
            # The browsable API should display pagination controls.
            self.display_page_controls = True

        self.request = request
        return list(self.page)

    def get_paginated_response(self, data):
        return Response(OrderedDict([
            ('count', self.page.paginator.count),
            ('next', self.get_next_link()),
            ('previous', self.get_previous_link()),
            ('results', data)
        ]))

    def get_page_size(self, request):
        if self.page_size_query_param:
            try:
                return _positive_int(
                    request.query_params[self.page_size_query_param],
                    strict=True,
                    cutoff=self.max_page_size
                )
            except (KeyError, ValueError):
                pass

        return self.page_size

    def get_next_link(self):
        if not self.page.has_next():
            return None
        url = self.request.build_absolute_uri()
        page_number = self.page.next_page_number()
        return replace_query_param(url, self.page_query_param, page_number)

    def get_previous_link(self):
        if not self.page.has_previous():
            return None
        url = self.request.build_absolute_uri()
        page_number = self.page.previous_page_number()
        if page_number == 1:
            return remove_query_param(url, self.page_query_param)
        return replace_query_param(url, self.page_query_param, page_number)

    def get_html_context(self):
        base_url = self.request.build_absolute_uri()

        def page_number_to_url(page_number):
            if page_number == 1:
                return remove_query_param(base_url, self.page_query_param)
            else:
                return replace_query_param(base_url, self.page_query_param, page_number)

        current = self.page.number
        final = self.page.paginator.num_pages
        page_numbers = _get_displayed_page_numbers(current, final)
        page_links = _get_page_links(page_numbers, current, page_number_to_url)

        return {
            'previous_url': self.get_previous_link(),
            'next_url': self.get_next_link(),
            'page_links': page_links
        }

    def to_html(self):
        template = loader.get_template(self.template)
        context = self.get_html_context()
        return template.render(context)

    def get_schema_fields(self, view):
        assert coreapi is not None, 'coreapi must be installed to use `get_schema_fields()`'
        assert coreschema is not None, 'coreschema must be installed to use `get_schema_fields()`'
        fields = [
            coreapi.Field(
                name=self.page_query_param,
                required=False,
                location='query',
                schema=coreschema.Integer(
                    title='Page',
                    description=force_text(self.page_query_description)
                )
            )
        ]
        if self.page_size_query_param is not None:
            fields.append(
                coreapi.Field(
                    name=self.page_size_query_param,
                    required=False,
                    location='query',
                    schema=coreschema.Integer(
                        title='Page size',
                        description=force_text(self.page_size_query_description)
                    )
                )
            )
        return fields

四、使用總結

雖然對於分頁來說，django rest framework 給我們提供了多種分頁，但是最為常用的還是第一種PageNumberPagination，推薦使用。

而第二種LimitOffsetPagination，使用場景是當數據量比較大時候，只關心其中某一部分數據，推薦使用。

CursorPagination類型分頁相對於PageNumberPagination有點在於，它避免了人為在url中自己傳入參數進行頁面的刷新（因為url不規則），缺點也顯而易見只能進行上下頁的翻閱。