Django Filter关联关系下OR过滤器的定义及模型关联问题

嘿，我刚好之前在项目里处理过类似的Django Filter关联模型OR过滤的需求，结合你给出的模型结构（我补全了Billing模型的合理字段），给你梳理几个实用的实现方法～

首先先明确下完整的模型结构（补全了必要的关联参数和状态字段）：

# models.py
from django.db import models

class Person(models.Model):
    first_name = models.CharField(max_length=20)
    last_name = models.CharField(max_length=20)

class PersonSession(models.Model):
    start_time = models.DateTimeField(auto_now_add=True)
    end_time = models.DateTimeField(null=True, blank=True)
    person = models.ForeignKey(Person, related_name='sessions', on_delete=models.CASCADE)

class Billing(models.Model):
    DEBT = 'DE'
    BALANCED = 'BA'
    CREDIT = 'CR'
    STATUS_CHOICES = [
        (DEBT, '欠款'),
        (BALANCED, '平衡'),
        (CREDIT, '结余'),
    ]
    status = models.CharField(max_length=2, choices=STATUS_CHOICES)
    session = models.OneToOneField(PersonSession, on_delete=models.CASCADE, related_name='billing')

方法一：自定义方法过滤器实现多字段OR搜索 #

如果需要做一个全局搜索框，让用户输入的内容同时匹配Person的姓名、关联Session的时间、关联Billing的状态（用OR逻辑连接），可以用自定义方法过滤器结合Q对象：

# filters.py
import django_filters
from django.db.models import Q
from .models import Person, Billing

class PersonFilter(django_filters.FilterSet):
    # 定义全局搜索过滤器
    global_search = django_filters.CharFilter(method='filter_global_search')

    def filter_global_search(self, queryset, name, value):
        # 用Q对象把多个跨模型的条件用OR连接
        return queryset.filter(
            Q(first_name__icontains=value) |
            Q(last_name__icontains=value) |
            # 匹配Session的开始时间年份（示例，可根据需求调整lookup_expr）
            Q(sessions__start_time__year__icontains=value) |
            Q(sessions__billing__status__icontains=value)
        ).distinct()  # 关键：避免关联查询导致的重复Person对象

    class Meta:
        model = Person
        fields = ['global_search']

方法二：重写filter_queryset统一处理OR条件 #

如果需要让多个独立的过滤器（比如姓名筛选、未结束Session筛选、欠款账单筛选）之间用OR逻辑组合，而不是默认的AND，可以重写FilterSet的filter_queryset方法：

# filters.py
import django_filters
from django.db.models import Q
from .models import Person, Billing

class PersonFilter(django_filters.FilterSet):
    name = django_filters.CharFilter(field_name='first_name', lookup_expr='icontains')
    has_unfinished_session = django_filters.BooleanFilter(field_name='sessions__end_time', lookup_expr='isnull')
    has_debt_billing = django_filters.BooleanFilter(method='filter_has_debt')

    def filter_has_debt(self, queryset, name, value):
        if value:
            return queryset.filter(sessions__billing__status=Billing.DEBT)
        return queryset

    def filter_queryset(self, queryset):
        # 初始化空的Q对象，用来拼接OR条件
        combined_q = Q()

        # 如果用户传入了姓名参数，添加姓名匹配的OR条件
        if self.data.get('name'):
            combined_q |= Q(first_name__icontains=self.data['name']) | Q(last_name__icontains=self.data['name'])
        
        # 如果用户勾选了"未结束Session"，添加对应的OR条件
        if self.data.get('has_unfinished_session') == 'True':
            combined_q |= Q(sessions__end_time__isnull=True)
        
        # 如果用户勾选了"有欠款账单"，添加对应的OR条件
        if self.data.get('has_debt_billing') == 'True':
            combined_q |= Q(sessions__billing__status=Billing.DEBT)

        # 只有当有条件时才过滤，否则返回原查询集
        if combined_q:
            return queryset.filter(combined_q).distinct()
        return queryset.distinct()

    class Meta:
        model = Person
        fields = ['name', 'has_unfinished_session', 'has_debt_billing']

方法三：针对特定过滤器组合修改为OR逻辑 #

如果只是需要某几个特定的过滤器之间用OR连接，其他保持默认的AND，可以在__init__方法里手动处理查询集：

# filters.py
import django_filters
from django.db.models import Q
from .models import Person, Billing

class PersonFilter(django_filters.FilterSet):
    session_start_after = django_filters.DateTimeFilter(field_name='sessions__start_time', lookup_expr='gte')
    billing_debt = django_filters.BooleanFilter(method='filter_billing_debt')

    def filter_billing_debt(self, queryset, name, value):
        if value:
            return queryset.filter(sessions__billing__status=Billing.DEBT)
        return queryset

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # 当同时传入session_start_after和billing_debt时，用OR连接这两个条件
        start_time = self.data.get('session_start_after')
        is_debt = self.data.get('billing_debt') == 'True'
        if start_time and is_debt:
            q1 = Q(sessions__start_time__gte=start_time)
            q2 = Q(sessions__billing__status=Billing.DEBT)
            self.queryset = self.queryset.filter(q1 | q2).distinct()

    class Meta:
        model = Person
        fields = ['session_start_after', 'billing_debt']

几个关键注意点 #

• 跨模型关联字段：用双下划线__来访问关联模型的字段，比如sessions__billing__status表示从Person到PersonSession（通过related_namesessions）再到Billing（通过related_namebilling）的status字段。
• 避免重复结果：因为关联查询（比如一对多）会生成笛卡尔积，导致同一个Person对象被多次返回，所以一定要记得调用distinct()去重。
• Q对象的使用：Q对象是Django中实现复杂查询条件的核心，|表示OR，&表示AND，~表示NOT。

内容的提问来源于stack exchange，提问作者motam