django-filter：Django 动态查询过滤的成熟方案

django-filter 是 Django 生态中一个老牌过滤库，目前已经积累了 4,685 个 Star：

django-filter 是一个可复用的 Django 应用。它的核心能力是通过声明式 API，让开发者基于 URL 查询参数对 QuerySet 进行动态过滤。接口设计思路和 Django 的 ModelForms 接近，熟悉 Django 表单的开发者上手很快。你不需要在视图里写一堆 if 判断来拼接过滤条件，而是把规则集中定义在 FilterSet 中。

这个项目已经维护多年，版本策略相当清晰。它采用 CalVer 双段式编号，格式如 21.1，第一段代表年份，第二段是当年内的发布序号。官方承诺持续支持当前所有 Django 版本、对应的 Python 版本，以及最新版 Django REST Framework。当 Python 或 Django 的某个版本到达生命周期终点，支持就会随之移除。如果必须引入破坏性变更，维护团队会尽量提供两年弃用期，给用户留出充足的升级缓冲时间。

安装

安装只需一行 pip 命令：

pip install django-filter

安装完成后，将 django_filters 添加到 INSTALLED_APPS 中：

INSTALLED_APPS=[...'django_filters',]

基础用法

定义 FilterSet 的写法与 ModelForm 高度相似。假设项目中有个 Product 模型，可以这样定义过滤器：

importdjango_filtersclassProductFilter(django_filters.FilterSet):classMeta:model=Product fields=['name','price','manufacturer']

在视图函数中使用：

defproduct_list(request):filter=ProductFilter(request.GET,queryset=Product.objects.all())returnrender(request,'my_app/template.html',{'filter':filter})

这段代码从 URL 查询参数中读取过滤条件，自动应用到 QuerySet。用户访问/products?name=foo&price=100这类地址时，返回结果就会自动带上对应的过滤逻辑。过滤器类内部会处理参数校验和查询构建，视图层保持干净。

Django REST Framework 集成

django-filter 也为 DRF 提供了专门的 FilterSet 子类和过滤后端。使用时要调整导入路径：

fromdjango_filtersimportrest_frameworkasfiltersclassProductFilter(filters.FilterSet):classMeta:model=Product fields=('category','in_stock')

集成方式和基础版基本一致。在 DRF 的视图或视图集中配置好 filter backend 后，列表接口就能自动支持按字段筛选。

对于需要给列表页增加查询过滤的 Django 项目，django-filter 是个值得考虑的选择。它把过滤逻辑从视图中抽离出来，API 设计直观，维护节奏稳定，版本策略成熟，已经过大量生产环境验证。

-filter 是个值得考虑的选择。它把过滤逻辑从视图中抽离出来，API 设计直观，维护节奏稳定，版本策略成熟，已经过大量生产环境验证。