queryset 并非字典，而是惰性数据库查询对象；若需插入额外数据（如补全缺失年份），应先转为列表再操作，避免破坏 queryset 的链式查询能力。
queryset 并非字典，而是惰性数据库查询对象；若需插入额外数据（如补全缺失年份），应先转为列表再操作，避免破坏 queryset 的链式查询能力。
在 Django 开发中，一个常见误区是将 QuerySet 当作 Python 字典或列表来直接修改。实际上，QuerySet 是对数据库查询的封装，具有惰性求值（lazy evaluation）特性——它本身不存储数据，只定义“如何获取数据”。因此，你无法像合并两个字典那样用 update() 或 | 操作符将自定义字典“注入”到 QuerySet 中。
正确的做法是：先执行查询、转换为 Python 列表，再以常规方式插入或追加字典项。以下是你原始查询的优化实现：
from django.db.models import Sum, Count, Q
from django.db.models.functions import TruncYear
# 执行查询并转为 list —— 此时真正访问数据库
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 对象
years.insert(0, {
'year': f'{current_year}-01-01', # TruncYear 输出格式为 'YYYY-01-01'
'total': 0,
'count': 0,
'earnings': 0,
'spent': 0,
})
⚠️ 关键注意事项：
-
TruncYear('timestamp')返回的是date类型（如datetime.date(2025, 1, 1)），因此判断年份时应使用.year属性，或统一格式化为字符串比较； -
list()强制求值会触发 SQL 查询，确保该操作发生在必要时机（如视图返回前），避免在中间件或模型层无意识触发； - 若后续还需对
years进行分页、过滤等操作，请改用itertools.chain+itertools.islice等流式处理，或在数据库层用UNION（通过QuerySet.union()）补全数据——但后者复杂度高，通常列表补全已足够。
✅ 总结：永远不要尝试“修改 QuerySet 本身”，而应将其视为不可变的查询定义；需要定制结果时，转为 list/dict 等原生结构后再处理，既清晰又可控。
