近日，多位MongoDB开发者在社区中反映了一个令人困惑的问题：在使用聚合管道的$set阶段更新嵌套对象时，字段并没有像预期那样被整体替换，而是出现了意料之外的“合并”行为——新对象的字段与原有对象的字段交织在一起，导致数据畸形。这一现象在涉及复杂文档结构的业务场景中尤为棘手，不少开发者直呼“踩坑”。

现象还原：一个典型的“合并”案例

假设我们有一个用户集合users，其中一条文档如下：

{
  "_id": 1,
  "name": "Alice",
  "profile": {
    "age": 30,
    "city": "New York"
  }
}

现在，我们希望用聚合管道的$set阶段将profile字段整体替换为一个新对象，例如：

db.users.aggregate([
  { $match: { _id: 1 } },
  { $set: { profile: { age: 31, job: "Engineer" } } }
])

按照直觉，最终文档的profile应该变成{ age: 31, job: "Engineer" }，原有的city字段应当消失。但实际结果却是：

{
  "_id": 1,
  "name": "Alice",
  "profile": {
    "age": 31,
    "city": "New York",
    "job": "Engineer"
  }
}

city字段被保留，age被覆盖，job被新增——整个对象被合并了，而非替换。这一行为在许多初接触聚合管道的开发者眼中无异于“玄学”。

根本原因：$set vs $replaceWith 的设计差异

要理解这一现象，必须区分MongoDB中两个看似相似但行为迥异的操作符：

  • $set（聚合阶段）：其本质是一个浅层合并操作。当作用于文档顶层时，它会合并指定的字段（如果字段已存在则覆盖，否则新增）。但对于嵌套文档，$set会递归地合并子文档字段，而不是替换整个子文档。这在官方文档中被称为“merges into existing fields”。

  • $replaceWith（或$replaceRoot）：则会用新文档完全替代当前文档，不保留任何原有字段。

因此，在上述案例中，$set将profile视为一个需要合并的深层对象，而不是一个原子单元，从而导致了“合并嵌套对象”的现象。

同样的场景，不同的表现：更新操作 vs 聚合操作

值得注意的是，使用updateOne配合$set操作符时，行为完全不同。在常规的更新操作中：

db.users.updateOne(
  { _id: 1 },
  { $set: { "profile": { age: 31, job: "Engineer" } } }
)

这会直接替换整个profile字段，得到预期的结果。这是因为更新操作的$set是字段级别的赋值，而聚合管道的$set是文档级别的合并。两者虽然名字相同，但实现机制和设计意图有着本质区别。

解决方案：三种方法实现嵌套对象替换

方法一：使用 $replaceWith 或 $replaceRoot

如果需要彻底替换整个文档的部分内容，最直接的方式是先构造新文档，然后完全替换。例如，利用$replaceWith配合$mergeObjects：

db.users.aggregate([
  { $match: { _id: 1 } },
  {
    $replaceWith: {
      $mergeObjects: [
        { _id: "$_id", name: "$name" },
        { profile: { age: 31, job: "Engineer" } }
      ]
    }
  }
])

这种方法显式地控制了哪些字段保留、哪些被替换，避免了意外合并。

方法二：使用 $addFields + $project

$addFields与$set行为相同（两者在聚合管道中本质等价），但如果我们紧接着使用$project来移除旧字段，可以达到效果。不过更简洁的方式是直接用$project指定需要保留的字段：

db.users.aggregate([
  { $match: { _id: 1 } },
  { $project: { name: 1, profile: { age: 31, job: "Engineer" } } }
])

注意：$project中的profile会直接覆盖原有内容，因为$project生成的是全新的文档。但缺点是必须显式列出所有保留的字段，否则除_id外其他顶层字段会丢失。

方法三：使用 $unset 删除旧字段后再 $set

如果业务逻辑需要在保持其他字段不变的情况下只替换嵌套对象，可以先删除旧字段，再设置新字段：

db.users.aggregate([
  { $match: { _id: 1 } },
  { $unset: "profile" },
  { $set: { profile: { age: 31, job: "Engineer" } } }
])

由于profile字段已被$unset删除，$set操作会将其视为一个全新的字段，从而直接赋值而非合并。

最佳实践：明确意图，避免隐式合并

针对这一常见陷阱，MongoDB官方社区建议开发者在聚合管道中处理嵌套对象时，遵循以下原则：

  1. 需要替换整个子文档时，优先使用$replaceWith。它最为安全，且语义清晰。
  2. 如果必须在$set后保持其他字段，可以先$unset再$set，或者用$project显式重构文档。
  3. 了解$set的合并特性，并将其用于“增量更新”场景。例如，只想新增或覆盖嵌套对象中的部分字段时，$set的合并行为恰好符合需求。

值得注意的是，MongoDB 5.0之后的版本中，$set的阶段行为保持不变，但官方文档对合并逻辑的描述更加详尽，同时引入了$replaceWith作为推荐替代方案。

结语

MongoDB作为一款灵活的NoSQL数据库，其聚合管道的设计既提供了强大的数据处理能力，也埋藏着一些需要开发者“自学”的陷阱。$set合并嵌套对象并非bug，而是设计使然——只是它并不符合大多数开发者对“设置”一词的直观理解。通过本文的分析，希望您能在下次遇到类似问题时，快速定位原因并选择合适的方案。毕竟，在文档型数据库中，理解“合并”与“替换”的区别，是通往高阶之路的必修课。