$set 不能安全合并嵌套对象，因其会完全替换整个字段而非字段级更新；必须用 updateOne + 聚合管道配合 $mergeObjects 实现一级合并，且不递归。
不能靠 $set 直接“合并”嵌套对象，必须用聚合管道更新（updateOne + pipeline）配合 $mergeObjects，否则会整块覆盖。
为什么 $set 不能用于嵌套字段的“安全合并”
当你对一个已有嵌套对象（如 package）执行 $set: { package: { newField: 'x' } }，MongoDB 会**完全替换**整个 package 字段，原有字段（如 package.parameter）直接消失。这不是“更新”，是“重写”。
- 错误示例：
$set: { "package": { "newField": "x" } }→ 原package.parameter丢失 - 点号路径写法（如
$set: { "package.newField": "x" }）只适用于已知、静态字段名，无法应对运行时动态结构 -
$push/$addToSet只作用于数组，对对象无效
用 $mergeObjects + $replaceWith 实现真正合并
这是 MongoDB 4.2+ 提供的原子级解决方案，语义等价于 PHP 的 array_merge($existing, $incoming)，但仅做一级合并（不递归）。
- 必须用
updateOne()或updateMany()的 pipeline 形式调用，不能用于简单$set -
$$ROOT引用当前文档完整快照，是合并的“基础项” -
$mergeObjects按数组顺序合并：后项同名字段覆盖前项，新增字段保留 - 示例（PHP driver v1.13+）：
$collection->updateOne(
['_id' => $id],
[
[
'$replaceWith' => [
'$mergeObjects' => [
'$$ROOT',
$obj // 如 ['package' => ['parameter' => 'v2', 'new' => 'test']]
]
]
]
]
);
注意：深度嵌套需手动展开或预处理
$mergeObjects 默认只合并一层对象，不会递归处理子对象。比如 package.nested.field 中的 nested 若本身是对象，它会被整体覆盖，而非字段级合并。
- 若需真正“深度合并”，得在应用层先 flatten / merge PHP 数组，再传入 pipeline
- 或在 pipeline 内部用
$cond+ 多层$mergeObjects手动构造，但复杂度陡增 - 常见误判点：以为
$mergeObjects自动递归 —— 它不递归，这是最容易忽略的限制
替代方案：点号路径 + 动态字段拼接（适合结构已知）
如果嵌套路径可预测（如数组索引固定、字段名来自白名单），用点号 + $set 更轻量、更直观。
- 例如更新
flashcards.0.side1：$set: { "flashcards.0.side1": "new content" } - 动态构建路径字符串：
"flashcards.${idx}.side1"，再作为 key 插入$set对象 - 优势：无需 pipeline，兼容所有 MongoDB 版本；劣势：无法应对任意深度/未知键名
真正麻烦的不是语法，而是混淆“覆盖”和“合并”的语义边界 —— 一旦把 $set 当成 array_merge 用，数据就静默丢了。
