annotate 通过 SQL 的 SELECT ... AS 在查询时动态添加字段，仅对当前 QuerySet 有效，需配合 values() 或 order_by() 实现分组聚合，不修改模型或数据库结构。
annotate 是怎么给 QuerySet 动态加字段的
annotate 不是修改模型定义，也不是往数据库里真加一列；它是在查询时，用 SQL 的 SELECT ... AS 语法，把聚合结果或表达式计算值临时“挂”在每条记录上。你调用 .values() 或遍历 QuerySet 时，这个字段才出现，且只对当前 QuerySet 生效。
- 必须配合
QuerySet使用，不能直接用在模型类或实例上 - 字段名由你指定（比如
annotate(total=Sum('price'))），不是自动推导的 - 如果没用
.values()分组，默认按原始表主键分组——这意味着单条记录的聚合（如Count('items')）其实是在算“这条记录关联了多少 items”，不是全表统计 - 常见误用：以为
annotate(avg_price=Avg('order__price'))能直接拿到平均值，结果发现很多行是None——因为默认 LEFT JOIN，空关联会返回 NULL，Avg对 NULL 安全，但字段本身存在，只是值为None
分组聚合必须搭配 values() 或 order_by() 吗
必须。Django 要知道按什么维度分组，否则就按整张表一条记录处理（相当于没分组）。但注意：.values('category') 会让 QuerySet 返回的是字典，不再是模型实例；而 .values('category').annotate(...) 才是标准分组聚合写法。
-
values('user_id')和values('user__id')效果相同，但前者更明确、性能略好（避免多一层 JOIN 解析） - 如果还想保留模型实例，又需要分组，得用
values_list('user_id', flat=True)配合后续过滤，或者改用prefetch_related+ Python 端聚合——annotate本身不支持“分组后仍返回完整模型实例” - 加了
order_by('user_id')但没values()，Django 会报错：FieldError: Cannot aggregate over the 'user_id' field because its name is not unique——这是提示你：排序字段未被显式选中，无法作为分组依据
Count、Sum、Avg 这些聚合函数容易踩什么坑
它们看着简单，但行为差异很大，尤其涉及外键和空值时。
Django Unfold
下载
提供使用 django-unfold (v0.56+) 构建高级 Django 管理界面的专业指导。当用户提及 django-unfold、unfold admin 等内容时使用此技能。
-
Count('orders')默认等价于Count('orders', distinct=True)，防止一对多导致重复计数；但如果你明确要算“订单行数”（不是订单数），得写Count('orders__item')并确认是否加distinct -
Sum('amount')遇到NULL字段会跳过，结果可能是None；想强制为 0，得用Coalesce(Sum('amount'), 0) -
Avg('rating')对NULL安全，但若整组都没数据，结果仍是None；前端渲染时容易崩，建议统一用Coalesce(Avg('rating'), 0) - 别在
annotate里用F()直接做除法，比如annotate(rate=F('success')/F('total'))——PostgreSQL 和 MySQL 对整数除法处理不同，MySQL 会截断，最好显式转成F('success') * 1.0 / F('total')
annotate 和 prefetch_related 能一起用吗
能，但顺序和目的完全不同：前者改 QuerySet 结构（加字段），后者优化关联对象加载（减少 N+1）。混用时要注意执行时机和字段可见性。
- 先
prefetch_related('tags')再annotate(tag_count=Count('tags'))—— 没问题，tag_count是数据库算的 - 先
annotate(tag_count=Count('tags'))再prefetch_related('tags')—— 也没问题，但tag_count值不会影响预取逻辑 - 错误用法：想用
annotate计算“每个 tag 的文章数”，却在模型层写Tag.objects.annotate(post_count=Count('article'))—— 这是对 Tag 表分组，没问题；但如果顺手加了.prefetch_related('article_set')，就会触发额外查询，且post_count和预取结果无直接关系 - 真正冲突点在于：如果你用
values()分组后，再prefetch_related，Django 会直接报错：Cannot prefetch QuerySet with .values() or .values_list()—— 因为预取需要模型实例，而values()返回字典
复杂的地方在于：同一个 annotate 调用里，可能混合了单值计算（如 F('a') + F('b')）、跨表聚合（Count('order__items')）、条件聚合（Sum(Case(When(...)))），每种背后生成的 SQL JOIN 策略都不同，稍不注意就会让查询变慢或结果错位。最稳妥的做法是——先用 .query 看 SQL，再用数据库 EXPLAIN 验证。
