$addFields 是 MongoDB 聚合管道中用于安全新增或覆盖字段的重要阶段，能够保留原有字段、支持嵌套路径写法，并可直接覆盖同名字段。从语义上看，它比 $project 更直观；在 MongoDB 4.2+ 中，它与 $set 完全等价。
$addFields 在 MongoDB 聚合管道中，主要用于安全地添加新字段或覆盖已有字段。它最大的优势是不会丢失原始文档中的其他字段，而且目标字段无论原本是否存在，都可以直接写入。这一点与 $set（v4.2+）完全一致，但 $addFields 更能准确表达“新增字段”的语义。如果您在使用 $project 时，经常需要重复列出全部字段，担心遗漏旧字段，或者想基于现有字段动态计算新值，却又不想重写整个输出结构，那么 $addFields 往往是更稳妥、更适合的选择。
为什么不能直接用 $project 添加字段？
使用 $project 添加字段时，所有没有显式声明的原始字段默认都会被排除。例如文档是 { name: "Alice", age: 30 }，执行：
{$project: { fullName: {$concat: ["$name", " (", {$toString: "$age"}, ")"]} }}
最终结果只会保留 { fullName: "Alice (30)" }，原来的 name 和 age 都会消失。而 $addFields 则会默认保留所有原始字段，只在其基础上追加新字段：
{$addFields: { fullName: {$concat: ["$name", " (", {$toString: "$age"}, ")"]} }}
输出结果就是 { name: "Alice", age: 30, fullName: "Alice (30)" }。
在实际开发中，常见的问题是聚合结果中的字段突然变少，关键 ID、创建时间或时间戳意外丢失，这种情况大多是因为误把 $project 当成了 $addFields 来使用。
$addFields 覆盖同名字段是否安全？
是安全的，而且这正是它的设计方式。如果目标字段已经存在，$addFields 会直接将其覆盖，无需先执行 $unset。例如：
{$addFields: { status: {$cond: [{ $gt: ["$score", 90] }, "A", "B"] } }}
无论原始文档中是否已有 status 字段，最终都会被新的计算结果替换。相比使用 $project 再手动列出其他所有字段后追加 status，这种写法更加简洁，也更不容易出错。
需要注意的是：
- 覆盖是浅层替换：如果原字段本身是对象，新值会整体替换该对象，而不是自动合并其内部的嵌套字段
- 它没有“仅在字段不存在时才添加”的内置机制，如需按条件新增，通常要配合
$cond或$ifNull进行明确判断 - 多个
$addFields阶段会按顺序执行，后面的同名字段会覆盖前面阶段生成的值
和 $set 的区别在哪？什么时候选哪个？
$set 是 $addFields 的别名，自 MongoDB 4.2 起两者完全等价。官方最新文档中已经将 $addFields 标记为 “deprecated alias”，但在实际执行效果上并没有区别。
选择时可以参考以下建议：
- 如果团队希望统一代码风格，优先使用
$set：语义更通用，也更接近 update 操作，便于新人理解 - 如果在旧的聚合管道中看到
$addFields，通常不必急着替换，它依然可以正常工作 - 如果聚合 pipeline 需要兼容 MongoDB 3.4+、早于 4.2 的版本，那么必须使用
$addFields；在 4.2+ 环境中二者可自由选择 - 二者性能没有差异，底层执行路径一致，不需要为了性能刻意切换
嵌套字段怎么添加？
$addFields 支持通过点号路径语法为嵌套字段赋值，但要特别注意：当父级路径不存在时，MongoDB 会自动创建中间对象。例如：
{$addFields: { "meta.lastModifiedBy": "admin", "meta.timestamp": {$now: {}} }}
即使原始文档中没有 meta 字段，也会自动生成类似 { meta: { lastModifiedBy: "admin", timestamp: ... } } 的结构。
这里常见的易错点包括：
- 路径拼写错误（例如写成
"meta..timestamp"）可能导致字段名异常，后续查询和使用都会出现问题 - 本来想更新
meta下的某个子字段，却误写成顶层字段名，结果创建了新的同名字段，而不是预期的嵌套结构 - 如果尝试用
$addFields为数组元素赋值（例如"tags.0"），通常不会按预期生效；数组索引更新一般需要使用$set配合位置操作符，不过这已经超出了$addFields的典型使用场景
真正更复杂的情况，通常出现在多层条件嵌套计算中——例如根据 items 数组内容动态生成 summary.totalPrice。这时表达式会快速变长，排查问题和调试的成本也会明显上升。更推荐的做法是不要把所有逻辑都塞进单个 $addFields 阶段，而是拆分为多个聚合阶段，每一步先生成一个中间字段，这样更方便验证结果，也更利于后续复用和维护。
