$addFields是MongoDB聚合管道里非常实用的一个阶段，它的作用是在文档流经管道时给每条文档追加新字段，字段的值可以是常量、原字段的引用，也可以是通过各种表达式运算符计算出来的结果。与直接修改集合不同，$addFields只是在聚合的内存中生成新的文档结构，不会对原始数据产生任何影响，因此特别适合做临时的数据加工和查询结果的二次处理。本文将从语法、典型场景、进阶用法和常见坑几个方面来详细讲解。
一、$addFields的基本语法与工作原理
$addFields的语法结构非常简单，它接收一个对象，对象的键就是你要添加的字段名，值就是这个字段对应的表达式。表达式可以是固定的值，也可以是字段路径引用，还可以是复杂的运算表达式。来看一个最基础的例子：
db.orders.aggregate([
{
$addFields: {
taxRate: 0.13, // 添加常量字段
totalWithTax: { // 添加计算字段
$multiply: ["$amount", 1.13]
}
}
}
])
上面这段代码会对orders集合中的每一条文档做处理。$amount表示引用当前文档中已有的amount字段，通过$multiply乘法运算符计算出含税金额，最终输出的文档既包含原有的所有字段，又多了taxRate和totalWithTax两个新字段。
$addFields的工作原理可以理解为「读取原文档，把新字段合并进去，再输出合并后的文档」。如果新添加的字段名和原有字段名相同，原有字段的值会被覆盖，这一点在后面讲坑的时候会再展开。另外，从MongoDB 3.4版本开始$addFields正式可用，它与$set阶段是等价的别名关系，写$set效果完全一样，习惯哪个用哪个即可。
二、$addFields与$project的核心区别
很多初学者容易把$addFields和$project混为一谈，因为两者都能改变文档的输出结构，但它们的行为有本质区别，用错了会导致字段莫名丢失。
最大的区别在于对未提及字段的处理。$project采用的是「白名单」模式，只有你明确写在里面的字段才会被保留，其余字段一律丢弃。而$addFields采用的是「保留并追加」模式，原文档的所有字段默认全部保留，你只管往里面加新东西。看下面这个对比：
// 写法一：$project，只输出amount和doubleAmount，其他字段全部丢失
db.orders.aggregate([
{
$project: {
amount: 1,
doubleAmount: { $multiply: ["$amount", 2] }
}
}
])
// 写法二：$addFields，原字段全部保留，额外多出doubleAmount
db.orders.aggregate([
{
$addFields: {
doubleAmount: { $multiply: ["$amount", 2] }
}
}
])
如果只是想在查询结果里补充一两个计算字段，同时希望原始信息不丢，$addFields明显更省事。而$project适合做最终的输出裁剪，控制返回给客户端的字段范围，减少网络传输量。实际项目中两者经常配合使用：先用$addFields算出中间结果，最后再用$project筛掉不需要的字段。
三、典型应用场景与实战示例
1. 电商订单金额计算
假设订单文档里有单价和数量，需要在查询时算出小计和含运费的总额，可以这样写：
db.orders.aggregate([
{
$addFields: {
subtotal: { $multiply: ["$price", "$quantity"] },
grandTotal: {
$add: [
{ $multiply: ["$price", "$quantity"] },
{ $ifNull: ["$shippingFee", 10] } // 运费缺省时按10元计算
]
}
}
}
])
这里用到了$ifNull运算符来处理运费字段可能不存在的情况，这是一种很常见的防御性写法。如果不做处理，字段缺失会导致计算结果直接变成null，容易在下游引发隐藏问题。
2. 嵌套文档与数组字段的处理
$addFields添加的字段可以嵌套在子文档里，只需要用点号路径写键名即可，这样输出结构会更清晰：
db.orders.aggregate([
{
$addFields: {
"summary.itemCount": { $size: "$items" },
"summary.maxPrice": { $max: "$items.price" },
"items.subtotal": { $multiply: ["$items.price", "$items.quantity"] }
}
}
])
注意最后一条，当items是一个数组时，$items.price会取出数组中每个元素的price形成一个数组，$multiply会逐元素对应相乘，直接给数组里每个元素生成一个subtotal字段。这种「自动展开数组」的特性在处理子文档数组时非常好用，能省去手动$unwind再$group的繁琐步骤。
3. 多阶段管道中引用前置结果
$addFields生成的字段在后续阶段中可以正常引用，这个特性让复杂的分步计算变得清晰。比如先按用户分组统计订单数，再判断用户等级：
db.orders.aggregate([
{
$group: {
_id: "$userId",
orderCount: { $sum: 1 },
totalAmount: { $sum: "$amount" }
}
},
{
$addFields: {
userLevel: {
$cond: {
if: { $gte: ["$totalAmount", 10000] },
then: "高级会员",
else: "普通会员"
}
}
}
}
])
$cond在这里充当三元表达式的作用，根据前面$group阶段算出的totalAmount来打上用户等级标签。整个流程一气呵成，不需要把中间结果落地到临时集合。
四、使用中的常见坑与注意事项
第一个坑是字段覆盖问题。如果$addFields指定的字段名和原文档字段名相同，原值会被新值覆盖，且没有任何警告。这在改写某些字段时是特性，但在无意中撞名时就是事故。建议在命名计算字段时加个前缀或后缀加以区分，比如calcTotal、amountV2。
第二个坑是数据类型。MongoDB是弱类型存储，如果字段里混存了字符串和数字，做乘法运算时会直接报错或返回null。稳妥的做法是在计算前用$convert做类型转换，并处理好转换失败的情况：
db.orders.aggregate([
{
$addFields: {
safeAmount: {
$convert: {
input: "$amount",
to: "double",
onError: 0, // 转换失败时返回0
onNull: 0 // 字段为null时返回0
}
}
}
}
])
第三个坑是性能层面。$addFields本身开销不大，但如果在它之前的阶段没有做好过滤，会对全量文档做计算，浪费CPU和内存。最佳实践是把$match放在管道最前面先缩小数据范围，再做字段计算。另外，如果聚合涉及分片集合，$addFields会在各个分片上执行，一般不会带来额外的网络开销，但要注意分片键不要被$addFields覆盖，否则可能导致路由异常。
总的来说，$addFields是一个「只加不减、低侵入」的管道阶段，掌握它的关键在于理解表达式的组合方式以及它与$project的分工。写聚合时先想清楚哪些字段是要保留的、哪些是要算出来的，再决定用哪个阶段，管道的可读性和执行效率都会好很多。
MongoDB聚合管道$addFields计算字段修改时间：2026-09-09 00:50:53