Django Unfold项目中多选过滤器与搜索功能冲突的解决方案

问题背景

在使用Django Unfold项目时，开发人员发现了一个关于多选过滤器与搜索功能交互的bug。当用户先使用多选过滤器筛选数据，再进行搜索操作时，部分筛选条件会丢失。这个问题主要出现在MultipleDropdownFilter和MultipleRelatedDropdownFilter这两种过滤器类型上。

问题重现

假设我们有一个SampleModelAdmin类，配置了多个多选过滤器：

@admin.register(SampleModel)
class SampleModelAdmin(ModelAdmin):
    list_filter = [
        ("status", MultipleDropdownFilter), 
        ("owner", MultipleRelatedDropdownFilter),
        ("writer", MultipleRelatedDropdownFilter),
    ]

操作步骤如下：

1. 进入变更列表页面
2. 应用多个筛选条件，URL可能变为：/admin/app/model/?status=open&status=closed&owner__id__exact=1&owner__id__exact=2&owner__id__exact=3&writer__id__exact=5
3. 在搜索框中输入"test"并搜索
4. 搜索后的URL变为：/admin/app/model/?q=test&status=open&owner__id__exact=1&writer__id__exact=5

可以看到，部分筛选条件（如status=closed和owner__id__exact=2等）在搜索操作后丢失了。

技术分析

这个问题源于Django不同版本对查询参数处理的差异：

1. 在Django 4.2中，ChangeList类只有params属性，它会"吞掉"多个相同参数名的值
2. 在Django 5.x中，ChangeList类新增了filter_params属性，能够正确处理多个相同参数名的值

问题的核心在于URL查询字符串中相同参数名的多个值（如status=open&status=closed）的处理方式。这种表示方式本身并不是最佳实践，但在Web开发中确实常见。

解决方案

经过讨论，开发团队决定采用自定义ChangeList类的方案来解决这个问题。这种方案具有以下优势：

1. 兼容性：可以同时支持Django 4.2和5.x版本
2. 灵活性：可以自定义参数处理逻辑
3. 可维护性：将特殊处理逻辑封装在ChangeList类中，不影响其他代码

实现方案的关键点包括：

1. 重写ModelAdmin.get_changelist_instance方法
2. 创建自定义的ChangeList子类
3. 在自定义ChangeList中正确处理多值参数

实现细节

自定义ChangeList类需要处理以下情况：

1. 当filter_params可用时（Django 5.x），直接使用它
2. 当filter_params不可用时（Django 4.2），回退到params并添加必要的处理逻辑
3. 确保搜索操作不会破坏已有的多值筛选条件

最佳实践建议

为了避免类似问题，建议开发者在处理多值筛选时：

1. 考虑使用更结构化的参数表示方式，如JSON或数组格式
2. 在前后端交互时明确参数的序列化和反序列化规则
3. 对关键功能进行跨版本兼容性测试
4. 考虑使用专门的筛选库或工具来处理复杂筛选场景

总结

Django Unfold项目中的这个bug展示了Web开发中常见的一个挑战：如何处理URL查询字符串中的多值参数。通过自定义ChangeList类的解决方案，不仅解决了当前的问题，还为未来可能出现的类似问题提供了可扩展的框架。这个案例也提醒我们，在开发通用组件时，跨版本兼容性和参数处理的一致性至关重要。