Django按用户注解查询集外键关联统一状态时消除重复对象

核心问题定位 #

当前实现会生成重复Widget记录的本质是SQL关联逻辑缺陷：

• 直接对user_status外键做无差别JOIN，只要一个Widget存在任意用户的状态记录，就会和该表产生行级匹配
• 即便关联的UserStatus不属于当前查询的用户，Case分支也无法命中对应条件，最终走到默认分支取Widget自身状态，导致同一个Widget因为关联了多个不同用户的UserStatus记录，生成多行不同注解值的结果
• 这种场景下追加.distinct()完全无效：因为两行结果的unified_status_id注解值不同，数据库会判定为独立行，无法被去重。

符合业务逻辑的实现方案 #

核心优化方向是从SQL层面避免不必要的JOIN行膨胀，有两种可落地的实现路径：

路径1：子查询注解（性能最优、无行膨胀风险） #

不做横向表连接，改用子查询逐行匹配当前用户的专属状态，从根源上杜绝重复行生成：

from django.db.models import Subquery, OuterRef, IntegerField, F, Case, When

class WidgetManager(models.Manager):
    def with_user_status(self, user: User = None):
        # 构造关联子查询：逐行匹配当前用户对应当前Widget的专属状态ID
        user_status_subquery = UserStatus.objects.filter(
            widget=OuterRef('pk'),
            user=user
        ).values('status_id')[:1]

        return self.annotate(
            unified_status_id=Case(
                # 存在用户专属状态时优先使用
                When(user_status_subquery__isnull=False, then=user_status_subquery),
                # 无匹配记录时沿用Widget自身的基础状态
                default=F('status_id'),
                output_field=IntegerField()
            )
        ).order_by('unified_status_id')

这种实现下，数据库不会把UserStatus表的行和Widget表做横向拼接，哪怕一个Widget存在几十个其他用户的状态记录，也不会影响当前查询的结果行数，是数据量大场景下的最优选择。

路径2：JOIN阶段过滤（兼容老版本Django写法） #

如果必须使用关联JOIN实现，需要在过滤阶段把所有不属于当前用户的UserStatus关联记录排除，这时候再用distinct才能生效：

from django.db.models import Q

class WidgetManager(models.Manager):
    def with_user_status(self, user: User = None):
        return self.annotate(
            unified_status_id=Case(
                When(user_status__user=user, then='user_status__status_id'),
                default=F('status_id'),
                output_field=IntegerField()
            )
        ).filter(
            # 仅保留两类有效记录：无关联UserStatus的Widget、关联的UserStatus属于当前用户
            Q(user_status__isnull=True) | Q(user_status__user=user)
        ).distinct().order_by('unified_status_id')

实现效果验证 #

使用上述任意一种实现运行测试代码，输出结果完全匹配预期：

带用户状态的Widget列表: [('Widget1', 1), ('Widget3', 1), ('Widget2', 2)]

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