【django开发手册】详解drf filter中DjangoFilterBackend，SearchFilter，OrderingFilter使用方式

• 作者简介：大家好，我是Zeeland，开源建设者与全栈领域优质创作者。
• CSDN主页：Zeeland
• 我的博客：Zeeland
• Github主页: Undertone0809 (Zeeland)
• 支持我：点赞+收藏⭐️+留言
• 介绍：The mixture of software dev+Iot+ml+anything

Django系列专栏

• 【django开发手册】Django 中使用自定义用户模型：一个比自带 User 更强的选择
• 【django开发手册】如何使用select_related进行一次连表查询
• 【django开发手册】drf通过添加自定义字段优化DRF序列化器，轻松实现高速API
• 【django开发手册】解决admin添加外键下拉显示外键的问题
• 【Django Rest Framework优化实践】ResponseResult、异常处理方法详解
• 【DRF】深度分析枚举类型在DRF中的序列化问题及解决方案
• 【django开发手册】关于django admin添加表信息的时候外键无法为空的问题解决方案
• 【django开发手册】django admin如何显示外键对应的字段
• 【django开发手册】DRF外键模型查询没有信息？教你实现序列化返回

前言

django restframework filter用于API的filter内容搜索，如对于/user接口，如果你想要查询其username字段，就使用/user/?username=jack的方式进行查询，这种方式就是通过drf的filter模块构建起来的，通过drf封装的filter模块，节约了自己写query代码的工作成本，而其底层本质是drf filter来帮你实现了数据库字段查询的功能，本文将重点介绍如何快速上手构建起drf的filter。

快速上手

首先先附上drf filter相关文档，没有什么比官方文档更加详细的了。

drf主要提供了DjangoFilterBackend，SearchFilter，OrderingFilter三种filter，通过三种不同的过滤器后端类，用于在API视图中实现数据过滤功能。

1. DjangoFilterBackend：
   DjangoFilterBackend是DRF提供的一个过滤器后端类，它使用第三方库django-filter来执行过滤操作。它允许你根据模型的字段值进行高级过滤，并提供了丰富的过滤选项。你可以通过在视图中指定filter_backends属性为[DjangoFilterBackend]来使用该过滤器后端。

   DjangoFilterBackend做到的事情：

   • 支持通过URL参数进行过滤，例如：/user/?username=jack 这样的 ?field=value 查询方式。
   • 提供了各种过滤选项，如精确匹配、范围查询、日期过滤、外键关联过滤等。
   • 自动生成基于模型定义的过滤表单（FilterSet）。

   使用DjangoFilterBackend可以让你快速、方便地实现复杂的模型字段过滤需求，尤其是当你的过滤器需求比较复杂且需要自定义的时候。

2. filters.SearchFilter：
   filters.SearchFilter是DRF提供的另一个过滤器后端类，用于执行文本搜索过滤。它基于数据库的全文搜索功能，可以在指定的字段上执行全文搜索，并返回匹配指定搜索词的结果。你可以通过将SearchFilter添加到视图的filter_backends属性列表中来使用它。

   filters.SearchFilter做到的事情：

   • 允许在API请求中通过URL参数指定搜索词，例如：?search=query。
   • 支持在指定的字段上进行全文搜索，并返回匹配搜索词的结果。
   • 可以自定义搜索字段、搜索算法和搜索运算符等。

   使用filters.SearchFilter可以轻松地实现基于文本内容的搜索功能，如在文章标题、标签或用户名称等字段上执行搜索。它适用于需求比较简单的文本搜索场景。

3. filters.OrderingFilter：

   filters.OrderingFilter是DRF提供的另一个过滤器后端类，用于对查询结果进行排序。它允许你通过URL参数指定排序字段，对返回的数据进行排序操作。

总结：

• DjangoFilterBackend主要用于基于模型字段进行高级过滤，支持丰富的过滤选项和自定义。
• filters.SearchFilter主要用于执行文本搜索过滤，支持在指定字段上进行全文搜索，并返回匹配搜索词的结果。
• filters.OrderingFilter主要用于执行数据排序。

你可以根据你的具体需求选择合适的过滤器后端来实现数据过滤功能。如果你需要更精细的过滤控制和多字段过滤，DjangoFilterBackend是一个不错的选择。如果你只需要简单的文本搜索功能，filters.SearchFilter就足够了。在某些情况下，你甚至可以同时使用它们来实现更复杂的过滤需求，而filters.OrderingFilter的使用相对较少，因为在大多数情况下，排序是后端的工作，在接口内部已经做了相关的排序处理再返回给前端。下面将介绍三个的快速上手使用方式。

DjangoFilterBackend

在Django Rest Framework中，可以使用filters模块来根据数据库字段进行查询。以下是一个示例代码片段，说明如何在DRF中实现根据数据库字段查询的功能：

首先，确保你已经安装了Django Rest Framework。你可以使用以下命令安装它：

pip install djangorestframework

接下来，在你的Django项目的设置文件（settings.py）中，添加django_filters到INSTALLED_APPS设置中：

INSTALLED_APPS = [
    ...
    'rest_framework',
    'django_filters',
    ...
]

接下来，在你的Django项目的设置文件（settings.py）中，添加DEFAULT_FILTER_BACKENDS到REST_FRAMEWORK设置中：

REST_FRAMEWORK = {
    'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend']
}

在你的应用程序的models.py文件中，定义你的模型类。例如，假设你有一个名为Book的模型，它有一个字段叫做title：

from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=100)
    # other fields...

接下来，创建一个序列化器（Serializer）来定义模型的序列化和反序列化行为。在你的应用程序的serializers.py文件中，创建一个名为BookSerializer的序列化器：

from rest_framework import serializers
from .models import Book

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = '__all__'  # 可以选择指定特定字段

现在，你可以在视图中使用过滤器查询数据库。在你的应用程序的views.py文件中，创建一个视图，并使用DRF的过滤器。以下是一个示例视图：

from rest_framework import viewsets
from .models import Book
from .serializers import BookSerializer
from django_filters.rest_framework import DjangoFilterBackend

class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all()
    serializer_class = BookSerializer
    filter_backends = [DjangoFilterBackend]
    filterset_fields = ['title']  # 指定要过滤的字段

在这个示例中，filterset_fields属性指定了你想要使用过滤器进行查询的字段。你可以根据需要添加或删除其他字段。

最后，在你的项目的URL配置文件（urls.py）中，将你的视图配置为路由，以便能够访问它：

from django.urls import include, path
from rest_framework import routers
from .views import BookViewSet

router = routers.DefaultRouter()
router.register(r'books', BookViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

以上代码将创建一个名为books的URL路径，它将映射到你的BookViewSet视图。

完成以上步骤后，你可以使用类似以下的请求来过滤查询结果：

GET /books?title=your-search-term

以上请求将返回具有匹配标题的书籍对象。

注意：在实际开发中，你可能还需要进行身份验证和权限控制，以确保只有经过授权的用户可以访问你的API。以上示例中并未包含这些功能，你可以根据需要进行进一步的开发和配置。

SearchFileter

SearchFilter类支持简单的基于单个查询参数的搜索，并且基于Django管理员的搜索功能。

使用时，可浏览的API将包括一个SearchFilter控件：

使用方式如下所示：

from rest_framework import filters

class UserListView(generics.ListAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    filter_backends = [filters.SearchFilter]
    search_fields = ['username', 'email']

运行应用之后，可以以如下方式运行接口：

http://example.com/api/users?search=russell

您还可以使用search_fields对外键和多对多字段进行查询，通过如下方式构建：

search_fields = ['username', 'email', 'profile__profession']

更多操作方式可以查看https://www.django-rest-framework.org/api-guide/filtering/#searchfilter

OrderingFilter

OrderingFilter类可以执行按照特定字段进行排序的操作，下面的示例展示了将查询出的users通过username和email进行排序的快速上手过程，首先构建一个ListAPIView。

class UserListView(generics.ListAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    filter_backends = [filters.OrderingFilter]
    ordering_fields = ['username', 'email']

然后你可以通过如下方式进行查询：

http://example.com/api/users?ordering=username

或者进行倒序查询

http://example.com/api/users?ordering=-username

总结

本文介绍了drf filter中DjangoFilterBackend，SearchFilter，OrderingFilter使用方式，更加进阶的使用方式，我更推荐你直接看官方文档，如有任何问题，欢迎交流讨论~