DRF之排序类源码分析

DRF之排序类源码分析

【一】排序类介绍

• 在Django REST framework (DRF)中，排序类用于处理API端点的排序操作，允许客户端请求按特定字段对数据进行升序或降序排序。
• 排序类是一种特殊的过滤类
• DRF提供了内置的排序类，并且你也可以自定义排序类以满足特定的需求。

【二】内置排序类OrderingFilter

• rest_framework.filters.OrderingFilter：这是DRF默认的排序类。
• 它允许客户端在API请求中使用 ?ordering= 参数来指定要排序的字段。
• 例如，?ordering=-created_at 将按 created_at 字段降序排序。

【1】使用

from rest_framework.filters import OrderingFilter

class MyModelListView(ListAPIView):
    queryset = MyModel.objects.all()
    serializer_class = MyModelSerializer
    filter_backends = [OrderingFilter]  # 添加你的自定义排序类
    ordering_fields = ['field1', 'field2']  # 定义允许排序的字段

• 执行流程
  • 当一个API请求到达时，Django REST framework将会执行视图的 get_queryset 方法来获取查询集。
  • 如果使用了 OrderingFilter 排序类，它会检查请求中是否包含 ?ordering= 参数。
  • 如果请求中包含 ?ordering= 参数，OrderingFilter 会根据参数的值对查询集进行排序。
  • 排序后的查询集将传递给视图进行进一步处理和返回。

【2】源码分析

class OrderingFilter(BaseFilterBackend):
    # The URL query parameter used for the ordering.
    ordering_param = api_settings.ORDERING_PARAM
    ordering_fields = None
    ordering_title = _('Ordering')
    ordering_description = _('Which field to use when ordering the results.')
    template = 'rest_framework/filters/ordering.html'

    # 获取客户端请求中的排序参数并返回排序顺序
    def get_ordering(self, request, queryset, view):
        """
        Ordering is set by a comma delimited ?ordering=... query parameter.

        The `ordering` query parameter can be overridden by setting
        the `ordering_param` value on the OrderingFilter or by
        specifying an `ORDERING_PARAM` value in the API settings.
        """
        # 首先从请求参数中获取排序参数（例如，?ordering=）
        params = request.query_params.get(self.ordering_param)
        if params:
            # 然后将其拆分成字段名
            fields = [param.strip() for param in params.split(',')]
            # 然后使用 remove_invalid_fields 方法来移除无效的字段名
            ordering = self.remove_invalid_fields(queryset, fields, view, request)
            # 如果排序参数有效
            if ordering:
                # 将返回排序顺序
                return ordering

        # No ordering was included, or all the ordering fields were invalid
        # 如果没有提供排序参数或所有字段都无效，将调用 get_default_ordering 方法返回默认排序
        return self.get_default_ordering(view)

    # 获取视图的默认排序顺序
    def get_default_ordering(self, view):
        # 如果视图类中定义了 ordering 属性
        ordering = getattr(view, 'ordering', None)
        if isinstance(ordering, str):
            # 它将返回该属性的值
            return (ordering,)
        # 否则将返回 None
        return ordering

    # 获取默认允许排序的字段
    def get_default_valid_fields(self, queryset, view, context={}):
        # If `ordering_fields` is not specified, then we determine a default
        # based on the serializer class, if one exists on the view.

        # 如果视图有 get_serializer_class 方法
        if hasattr(view, 'get_serializer_class'):
            try:
                # 尝试从序列化器类中获取字段列表
                serializer_class = view.get_serializer_class()
            except AssertionError:
                # Raised by the default implementation if
                # no serializer_class was found
                serializer_class = None
        else:
            serializer_class = getattr(view, 'serializer_class', None)

        # 如果没有序列化器类，将引发 ImproperlyConfigured 异常
        if serializer_class is None:
            msg = (
                "Cannot use %s on a view which does not have either a "
                "'serializer_class', an overriding 'get_serializer_class' "
                "or 'ordering_fields' attribute."
            )
            raise ImproperlyConfigured(msg % self.__class__.__name__)

        # 获取到模型类的模型
        model_class = queryset.model
        # 校验模型类中的字段
        model_property_names = [
            # 'pk' is a property added in Django's Model class, however it is valid for ordering.
            attr for attr in dir(model_class) if isinstance(getattr(model_class, attr), property) and attr != 'pk'
        ]	

		# 列出模型字段和查询注释字段
        return [
            (field.source.replace('.', '__') or field_name, field.label)
            for field_name, field in serializer_class(context=context).fields.items()
            if (
                not getattr(field, 'write_only', False) and
                not field.source == '*' and
                field.source not in model_property_names
            )
        ]

    # 获取允许排序的字段
    def get_valid_fields(self, queryset, view, context={}):
        # 如果视图定义了 ordering_fields，将返回该字段，否则将根据 ordering_fields 的值执行不同的逻辑
        valid_fields = getattr(view, 'ordering_fields', self.ordering_fields)

        # 如果 ordering_fields 是 None
        if valid_fields is None:
            # Default to allowing filtering on serializer fields
            # 将调用 get_default_valid_fields 方法获取默认字段列表
            return self.get_default_valid_fields(queryset, view, context)

        # 如果 ordering_fields 是 __all__
        elif valid_fields == '__all__':
            # View explicitly allows filtering on any model field

            # 将允许对模型的所有字段进行排序
            valid_fields = [
                (field.name, field.verbose_name) for field in queryset.model._meta.fields
            ]
            valid_fields += [
                (key, key.title().split('__'))
                for key in queryset.query.annotations
            ]
        else:
            # 否则，将返回视图中定义的排序字段
            valid_fields = [
                (item, item) if isinstance(item, str) else item
                for item in valid_fields
            ]

        # 返回允许排序的字段
        return valid_fields

    # 移除无效的排序字段
    def remove_invalid_fields(self, queryset, fields, view, request):

        # 接受一个字段列表，然后使用 get_valid_fields 方法获取允许的字段列表
        valid_fields = [item[0] for item in self.get_valid_fields(queryset, view, {'request': request})]

        # 校验有效字段的列表
        def term_valid(term):
            if term.startswith("-"):
                term = term[1:]
            return term in valid_fields

        # 最后，它将返回一个仅包含有效字段的列表
        return [term for term in fields if term_valid(term)]

    # 对查询集进行排序
    def filter_queryset(self, request, queryset, view):
        # 调用 get_ordering 方法获取排序顺序
        ordering = self.get_ordering(request, queryset, view)

        if ordering:
            # 然后使用 order_by 方法对查询集进行排序
            return queryset.order_by(*ordering)

        # 如果没有提供排序参数，将返回原始查询集
        return queryset

    # 为HTML模板提供上下文数据
    def get_template_context(self, request, queryset, view):
        # 首先，它调用 get_ordering 方法获取当前的排序顺序（如果有的话），并将其存储在变量 current 中
        current = self.get_ordering(request, queryset, view)
        #  # 如果没有排序顺序，将设置 current 为 None
        current = None if not current else current[0]

        # 创建一个空列表 options，用于存储可用的排序选项
        options = []

        # 创建一个上下文字典 context 包含以下键值对
        context = {
            # 存储请求对象，以便在模板中访问请求信息
            'request': request,
            # 存储当前排序状态（可能为 None）
            'current': current,
            # 存储排序参数名称（例如，ordering）
            'param': self.ordering_param,
        }

        # 循环遍历可用的排序字段
        # 使用 get_valid_fields 方法获取可用的排序字段
        for key, label in self.get_valid_fields(queryset, view, context):

            # 将字段名称和升序排序标签添加到 options 列表。
            options.append((key, '%s - %s' % (label, _('ascending'))))

            # 将字段名称加上 '-' 前缀和降序排序标签添加到 options 列表。
            options.append(('-' + key, '%s - %s' % (label, _('descending'))))

        # 将包含排序选项的列表添加到上下文字典中，以便在模板中访问
        context['options'] = options

        # 返回一个包含有关当前排序状态和可用排序选项的上下文字典
        return context

    # 生成HTML表示的排序控件
    def to_html(self, request, queryset, view):

        # 获取渲染器
        template = loader.get_template(self.template)

        # 获取上下文对象
        context = self.get_template_context(request, queryset, view)

        # 使用模板来渲染排序控件，并返回HTML代码
        return template.render(context)

    def get_schema_fields(self, view):
        # 这是一个断言语句，用于确保Core API库已安装。
        # 如果未安装，将引发AssertionError异常，提示用户需要安装Core API库才能使用这个方法
        assert coreapi is not None, 'coreapi must be installed to use `get_schema_fields()`'
        # 用于确保Core Schema库已安装。
        # 如果未安装，将引发AssertionError异常，提示用户需要安装Core Schema库才能使用这个方法。
        assert coreschema is not None, 'coreschema must be installed to use `get_schema_fields()`'

        # 如果Core API和Core Schema库都已安装，该方法将返回一个包含排序参数描述信息的列表。
        return [
            # 具体来说，它创建了一个coreapi.Field对象，该对象描述了排序参数的属性
            coreapi.Field(
                # 定义参数的名称，通常是ordering
                name=self.ordering_param,
                # 指示参数是否是必需的。在这里，它设置为False，因为排序参数是可选的
                required=False,
                # 指示参数在请求的查询字符串中
                location='query',
                # 定义参数的架构。在这里，它指定参数的类型为字符串，并提供了标题和描述信息，这些信息将出现在API文档中
                schema=coreschema.String(
                    title=force_str(self.ordering_title),
                    description=force_str(self.ordering_description)
                )
            )
        ]

    # 返回一个包含描述排序参数的操作参数信息的列表
    def get_schema_operation_parameters(self, view):
        return [
            {
                #  定义参数的名称，通常是 ordering
                'name': self.ordering_param,
                # 指示参数是否是必需的。在这里，它设置为 False，因为排序参数是可选的。
                'required': False,
                # 指示参数在请求中的位置。在这里，它设置为 'query'，表示排序参数位于查询字符串中。
                'in': 'query',
                # 提供有关参数的描述信息，使用 force_str(self.ordering_description) 获取排序参数的描述
                'description': force_str(self.ordering_description),
                # 定义参数的架构，包含有关参数类型的信息。在这里，它指定参数的类型为字符串，表示排序参数的值应该是字符串类型
                'schema': {
                    'type': 'string',
                },
            },
        ]

【三】自定义排序类

【1】使用

from rest_framework.filters import OrderingFilter

class CustomOrderingFilter(OrderingFilter):
    def get_ordering(self, request, queryset, view):
        # 获取客户端传递的排序参数
        ordering = request.query_params.get('ordering')
        if ordering:
            # 在此处可以根据自定义逻辑修改排序方式
            return [ordering]
        return super().get_ordering(request, queryset, view)

class MyModelListView(ListAPIView):
    queryset = MyModel.objects.all()
    serializer_class = MyModelSerializer
    filter_backends = [CustomOrderingFilter]  # 添加你的自定义排序类
    ordering_fields = ['field1', 'field2']  # 定义允许排序的字段

【2】分析

• 继承 OrderingFilter
• 重写 get_ordering 方法
• 自定义 过滤条件
• 将过滤后的视图视图集返回给视图函数进一步调用