本文介绍如何使用 MongoDB 的 findOneAndUpdate 配合 $setOnInsert 和 upsert: true，在更新时仅当文档不存在时才插入默认字段（如 age），避免覆盖已有数据，兼顾原子性与安全性。
本文介绍如何使用 mongodb 的 `findoneandupdate` 配合 `$setoninsert` 和 `upsert: true`，在更新时仅当文档不存在时才插入默认字段（如 `age`），避免覆盖已有数据，兼顾原子性与安全性。
在 MongoDB 中，向已有文档“条件性添加新字段”是一个高频需求——例如为存量用户文档统一补全 age 字段，但又不希望误改已存在的值。此时，直接使用 updateOne 或 updateMany 的 $set 操作会无差别写入，存在覆盖风险；而单纯启用 upsert: true 又可能因匹配条件过宽导致意外创建重复文档。
正确的做法是：利用 $setOnInsert 操作符 + upsert: true 的组合机制。$setOnInsert 仅在 upsert 触发（即文档不存在、需插入新文档）时生效；若文档已存在，则该操作被忽略，从而确保已有字段（如 name）和新增字段（如 age）均不受影响。
以下为推荐写法（以 Node.js MongoDB Driver 或 Shell 均适用）：
db.collection("users").findOneAndUpdate(
{ key: 1 }, // 查询条件：定位目标文档
{
$set: { name: "abc" }, // ✅ 若文档存在，更新 name（可选）
$setOnInsert: {
key: 1,
name: "abc",
age: 20
}
},
{
upsert: true, // 允许插入新文档
returnDocument: "after" // 返回更新/插入后的完整文档（v4.0+ 推荐用此参数替代已弃用的 returnOriginal）
}
)⚠️ 关键注意事项：
- $setOnInsert 仅作用于 upsert 场景，对纯更新（update）无效，因此它天然适配“有则不变、无则补全”的语义；
- 不要将必需字段（如 _id 或唯一索引字段）放在 $setOnInsert 中重复声明——MongoDB 会自动处理 _id，而业务主键（如 key）若已在查询条件中出现，重复设置虽不报错但属冗余；
- 若目标是为所有匹配文档统一添加字段（无论是否已存在），应改用 $set 而非 $setOnInsert，例如：{ $set: { age: { $ifNull: ["$age", 20] } } } 实现“空值填充”；
- 在高并发场景下，findOneAndUpdate 是原子操作，可避免竞态条件（如两次查询都未命中、导致重复插入）。
总结：当目标是“安全扩展现有文档结构”而非“强制重写”，$setOnInsert 是比 $set 更精准、更可控的选择。它让 upsert 不再只是“插入兜底”，而是成为“智能初始化”的核心工具。
