queryset 并非字典，而是惰性数据库查询对象；若需插入额外数据（如补全缺失年份），应先转为列表再操作，避免破坏 queryset 的链式查询能力。
queryset 并非字典，而是惰性数据库查询对象；若需插入额外数据（如补全缺失年份），应先转为列表再操作，避免破坏 queryset 的链式查询能力。
在 Django 开发中，一个常见误区是将 QuerySet 当作 Python 字典或列表来直接修改——例如试图用 dict.update() 或 + 操作符合并字典与 QuerySet。但事实上，QuerySet 是一个惰性、可链式操作的查询封装对象，不是实际的数据容器，更不是 dict。它仅在被遍历、切片、序列化或调用 .list() 等方法时才真正执行 SQL 查询并返回结果。
因此，当你需要“向 QuerySet 中添加一条人工构造的记录”（比如确保当前年份始终存在，即使数据库中无对应交易），正确做法是：先求值（list()），再以 Python 列表方式插入或追加字典项。
以下是一个优化后的实现示例（适配你的原始查询逻辑）：
from django.db.models import Sum, Count, Q
from django.db.models.functions import TruncYear
# 执行查询并立即转为 list —— 此时 QuerySet 被求值，得到 Python 字典列表
years = list(
Transactions.objects
.annotate(year=TruncYear('timestamp'))
.values('year')
.annotate(
total=Sum('amount'),
earnings=Sum('amount', filter=Q(amount__gt=0)),
spent=Sum('amount', filter=Q(amount__lt=0)),
count=Count('id'),
)
.order_by('-year')
)
# 检查是否已包含当前年份（例如 2025），若无则前置插入
current_year = 2025
if not years or years[0]['year'].year != current_year: # 注意：TruncYear 返回 date 对象，取 .year
years.insert(
0,
{
'year': current_year,
'total': 0,
'count': 0,
'earnings': 0,
'spent': 0,
}
)
⚠️ 关键注意事项：
-
TruncYear('timestamp')返回的是date类型（如datetime.date(2025, 1, 1)），因此判断年份时需用item['year'].year，而非直接比较整数；若希望year字段为整数，可改用ExtractYear：from django.db.models.functions import ExtractYear .annotate(year=ExtractYear('timestamp')) # 返回 int -
list()会触发数据库查询，此后years是纯内存数据结构，不再具备 QuerySet 的.filter()、.exclude()等能力——这正是你所需要的：此时它就是一个标准的 Python 列表，可自由增删改查。 - 若后续还需分页、过滤等数据库级操作，请勿提前
.list()；而应通过UNION或CASE WHEN在 SQL 层补全数据（较复杂，通常不必要）。
✅ 总结：
不要尝试“修改 QuerySet”，而应“消费 QuerySet 后处理结果”。将 QuerySet → list[dict] 视为数据管道中的自然转换节点——清晰、安全、符合 Django 设计哲学。
