Django-Filter 迁移指南：从旧版本升级到最新版的最佳实践

Django-Filter 迁移指南：从旧版本升级到最新版的最佳实践

【免费下载链接】django-filter 项目地址: https://gitcode.com/gh_mirrors/dja/django-filter

前言

Django-Filter 作为 Django 生态中强大的过滤组件，在版本迭代过程中进行了多次重大更新。本文将全面解析从旧版本迁移到 2.0 和 1.0 版本的关键变化点，帮助开发者顺利完成升级工作。

启用警告提示

在迁移过程中，启用 Python 的警告系统能帮助我们快速定位问题：

# 显示首次出现的警告
python -W once manage.py test

# 将警告转为异常（显示完整堆栈）
python -W error manage.py test

迁移至 2.0 版本的重大变更

1. Filter.lookup_expr 列表形式移除

旧版本中允许为 lookup_expr 指定列表或 None 值，新版本中必须使用 LookupChoiceFilter 替代。

2. FilterSet.filter_for_reverse_field 方法移除

现在 filter_for_field 方法已统一处理正向和反向关系，同时反向关系也会遵循 Meta.filter_overrides 的设置。

3. 视图相关属性重命名

为提高一致性，多个视图相关属性进行了重命名：

• filter_class → filterset_class
• filter_fields → filterset_fields
• default_filter_set → filterset_base
• get_filter_class() → get_filterset_class()

4. Meta.together 选项移除

该选项已被废弃，建议通过重写 Meta.form 类的 clean 方法实现类似功能。

5. 严格模式处理移至视图层

FILTERS_STRICTNESS 设置、Meta.strict 选项和 FilterSet 初始化参数 strict 都已移除，现在需要在视图层控制严格行为。

6. Filter.name 重命名为 field_name

为避免歧义，name 属性更名为 field_name，更清晰地表示这是用于过滤的字段名。

7. Filter.widget 和 Filter.required 移除

这些参数现在统一存放在 Filter.extra 字典中。

8. MultiWidget 替换为 SuffixedMultiWidget

RangeWidget、DateRangeWidget 等现在继承自 SuffixedMultiWidget，查询参数后缀从 _0/_1 变为更具语义化的 _min/_max 等。

迁移至 1.0 版本的重要变更

1. MethodFilter 和 Filter.action 被 Filter.method 取代

新版本统一使用 method 参数，可以接收可调用对象或 FilterSet 方法名。方法签名新增 name 参数表示模型字段名。

# 新版本写法
class UserFilter(FilterSet):
    last_login = filters.CharFilter(method='filter_last_login')

    def filter_last_login(self, qs, name, value):
        return qs.filter(**{name: value})

2. QuerySet 方法不再自动代理

__iter__()、count() 等方法不再自动代理，需要显式通过 .qs 属性调用。

3. Meta.fields 必须显式声明

旧版本中未指定 Meta.fields 时会自动生成所有模型字段的过滤器，这存在安全隐患。新版本必须显式设置：

# 允许所有字段
fields = '__all__'

# 或排除特定字段
exclude = ['password']

4. FilterSet 选项移至 Meta 类

多个选项迁移到 Meta 类中以避免命名冲突：

• filter_overrides
• strict
• order_by_field

5. 排序功能由 OrderingFilter 接管

Meta.order_by 和 Meta.order_by_field 被废弃，建议使用专门的 OrderingFilter。

6. 帮助文本设置变更

FILTERS_HELP_TEXT_FILTER 和 FILTERS_HELP_TEXT_EXCLUDE 设置不再有效，新版本会自动生成更具描述性的标签。

升级建议

1. 分阶段升级：建议先升级到 0.15 过渡版本，处理所有警告后再升级到最新版
2. 全面测试：升级后需对过滤功能进行全面测试，特别是涉及范围查询和自定义过滤逻辑的部分
3. 模板调整：如果使用 DRF 集成，确保 django_filters 在 INSTALLED_APPS 中

通过遵循本指南，开发者可以系统性地完成 Django-Filter 的版本迁移工作，充分利用新版本的改进特性。

【免费下载链接】django-filter 项目地址: https://gitcode.com/gh_mirrors/dja/django-filter