Django REST Framework 集成 django-filter 配置与使用详解

苏见山

发布时间：2026-10-14 | 3人浏览过

原创

本文详解在Django REST Framework中集成django-filter的方法。重点说明需在settings中注册应用并配置DEFAULT_FILTER_BACKENDS，否则过滤功能不生效。通过示例展示如何定义自定义过滤器类（如NumberFilter、CharFilter），结合ViewSet配置filter_backends，并正确注册URL路由，实现高效的数据筛选与搜索功能。

DRF集成django-filter注意事项

在Django REST Framework（DRF）中集成使用django-filter时，有几个关键注意事项需要明确。

必须在项目的settings配置文件中正确加载相关设置，而不仅仅是安装django-filter包。如果忽略这一步，Django应用启动时不会报错，但数据过滤功能将无法正常工作。


“`
INSTALLED_APPS = [
‘django_filters'
]

REST_FRAMEWORK = {
‘DEFAULT_FILTER_BACKENDS': ( ‘django_filters.rest_framework.DjangoFilterBackend',
),
}

接下来补充一些关于rest_framework内置filters与django-filters混合使用的知识，以便更好地过滤和搜索数据。

视图集与过滤器配置

首先看视图（View）部分的配置。


from rest_framework.pagination import PageNumberPagination
from rest_framework import mixins
from rest_framework import viewsets
from rest_framework import filters

from django_filters.rest_framework import DjangoFilterBackend

from .models import Goods
from .serializers import GoodsSerializer
# 导入过滤器类
from .filters import GoodsFilter

class GoodsPagination(PageNumberPagination):
  page_size = 10
  page_size_query_param = "page_size"
  page_query_param = "p"
  max_page_size = 100

class GoodsListViewSet(mixins.ListModelMixin, viewsets.GenericViewSet):
  # 指定queryset
  queryset = Goods.objects.all()

  # 指定序列化类
  serializer_class = GoodsSerializer

  # 指定分页类
  pagination_class = GoodsPagination

  # 添加过滤器 这里可以吧django-filter过滤器添加进来 和 rest_framework的filters添加进来一起用, 也可以单个用, 看你的需求
  filter_backends = [DjangoFilterBackend, filters.SearchFilter]

  # 只需要简单的基于等同的过滤，则可以filter_fields在视图或视图集上设置属性，列出要过滤的字段集。
  # 等同就是根据你过滤的字段的数据必须跟数据库里那个字段的数据相同
  # filter_fields = ['name', 'shop_price']

  # 指定过滤器类
  filter_class = GoodsFilter

  search_fields = ['name', 'goods_brief', "goods_desc"]

我们需要根据具体业务需求定义过滤器类，这是实现精确过滤的核心。


import django_filters

from .models import Goods

class GoodsFilter(django_filters.rest_framework.FilterSet):
  """
  商品的过滤类
  """

  # 大于这个值 name指定字段 lookup_expr过滤条件
  # NumberFilter 数字类型
  price_min = django_filters.NumberFilter(name="shop_price", lookup_expr="gte")
  # 小于这个值
  price_max = django_filters.NumberFilter(name="shop_price", lookup_expr="lte")

  # name模糊查询, 不指定过滤条件, 必须全部匹配
  # CharFilter字符串类型
  name = django_filters.CharFilter(name="name", lookup_expr="icontains")

  class Meta:
    # 指定模型类
    model = Goods
    # 显示这两个字段
    fields = ["price_min", "price_max", "name"]

Settings配置与URL路由

同时，确保settings文件中的配置正确无误，包括应用注册和DRF的全局设置。


INSTALLED_APPS = [
  # drf过滤器 也 是xadmin的过滤器
  'django_filters',
  'rest_framework',
]

最后，配置URL路由，将视图集注册到路由器中，以便通过URL访问过滤后的数据。


from django.conf.urls import url, include

from rest_framework.routers import DefaultRouter

from goods.views import GoodsListViewSet
# 生成一个注册器实例对象
router = DefaultRouter()
# 将需要自动生成url的接口注册
# 配置goods的url
router.register(r'goods', GoodsListViewSet, base_name="goods-list")

urlpatterns = [
  # 自动生成url
  url(r"^", include(router.urls)),
]

以下是配置完成后的效果展示。