annotate() 更适合返回自定义字段，因为它在 sql 层添加 select 子句，支持聚合与表达式计算；而 select_related()/prefetch_related() 仅预取关联对象，不生成新字段。
为什么 annotate() 比 select_related() 或 prefetch_related() 更适合返回自定义字段
因为 select_related() 和 prefetch_related() 只能预取关联对象（生成额外的 model 实例），无法在查询结果中新增计算字段或聚合值；而 annotate() 是在 SQL 层直接添加 SELECT 子句，支持 Count、Sum、F、Case/When 等表达式，真正实现“查出来就是你要的结构”。
常见错误现象：AttributeError: 'Book' object has no attribute 'author_name' —— 试图用 values() + annotate() 后再访问未声明的字段，或误以为 annotate() 会自动挂载到 model 实例上（它只影响 QuerySet 的字典/元组结构）。
- 必须配合
values()或values_list()使用，否则 annotation 字段不会出现在结果里（Django 默认返回 model 实例，不展示 annotation） -
annotate()在values()之后调用，会按values()的分组键做聚合；顺序反了（先annotate()再values()）可能引发意外分组 - 跨多表字段引用需用双下划线，如
author__name；但聚合时若涉及外键反向关系（如 Book ← Author ← Profile），要用author__profile__bio，且确保外键存在、非空，否则该行会被排除（INNER JOIN 行为）
用 annotate() 实现带作者名和评论数的图书列表
假设模型： Book（title, author 外键到 Author），Comment（book 外键到 Book）。目标是返回每本书的标题、作者名、评论总数。
正确写法：
from django.db.models import Count, F
from myapp.models import Book
qs = Book.objects.values(
'id',
'title',
'author__name'
).annotate(
comment_count=Count('comment'),
author_name=F('author__name')
).order_by('-comment_count')
说明：
-
values()明确列出要返回的字段，包括跨表字段author__name；这是后续annotate()分组的基础 -
Count('comment')统计正向外键关联的评论数（Django 自动处理 JOIN） -
F('author__name')把已选的author__name再“重命名”为author_name，避免字段名含双下划线；注意F()不是聚合函数，但它在annotate()中可作表达式使用 - 结果每项是
dict，含'id','title','author__name','comment_count','author_name'键 —— 若不想保留author__name，就别在values()里写它，只靠F()注入新字段
多表联查时 annotate() 遇到 NULL 外键怎么办
当 Book.author 允许为空，而你仍想查出所有书（含 author 为 NULL 的），直接 values('author__name') 会导致这些记录被过滤掉 —— 因为 Django 默认用 INNER JOIN。
解决方法：改用 LEFT OUTER JOIN，通过 models.ForeignKey(..., null=True) 定义 + 显式指定 join 行为，但更简单的是用 Coalesce 和 OuterRef 配合 Subquery，或直接改用 annotate() + Case/When 处理空值：
from django.db.models import Count, Case, When, IntegerField, Value, Q
from django.db.models.functions import Coalesce
qs = Book.objects.values('id', 'title').annotate(
author_name=Coalesce('author__name', Value('Unknown')),
comment_count=Count('comment', filter=Q(comment__is_active=True))
)
关键点：
-
Coalesce('author__name', Value('Unknown'))在 SQL 层做空值替换，避免因 NULL 导致整行丢失 -
Count(..., filter=...)是条件聚合，只统计满足条件的关联记录（比如仅活跃评论），比先filter()再annotate()更准确（后者会过滤掉无匹配评论的书） - 不要用
author__name__isnull=False去filter()，那会丢数据；NULL 处理必须发生在 SELECT 或 JOIN 层，而不是 WHERE
性能陷阱：annotate() + values() 顺序和索引影响
如果 values() 字段没建索引，尤其是跨表字段（如 author__name），数据库可能无法高效分组，导致慢查询。更隐蔽的问题是：当你在 annotate() 里用 F() 引用未出现在 values() 中的字段，Django 会静默忽略该字段（不报错），但结果里没有它。
- 执行前加
.explain()查看 SQL 执行计划，确认是否用到索引，有无Using temporary; Using filesort - 对高频聚合字段（如
author_id、status）建立复合索引，例如Index(fields=['author_id', 'created_at']) - 避免在
annotate()中嵌套过多子查询（如多个Subquery），它们会在每行重复执行；优先用JOIN+Count或Sum - 调试时打印 SQL：
print(qs.query)，注意观察生成的GROUP BY子句是否符合预期 —— 它完全由values()决定
最常被忽略的一点：annotate() 返回的是不可变的 QuerySet，一旦调用 values()，后续不能再用 filter() 对 annotation 字段过滤（比如 .filter(comment_count__gt=0) 是合法的，但 .filter(author_name='xxx') 会报错，因为 author_name 是 annotation 别名，不是数据库字段）。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
