本文详解如何使用 MongoDB 的 $setOnInsert 操作符配合 upsert 实现“仅在插入时设置字段”，从而在更新现有文档时不覆盖原有数据，同时确保新字段（如 age）在文档首次创建时被正确初始化。
本文详解如何使用 mongodb 的 `$setoninsert` 操作符配合 `upsert` 实现“仅在插入时设置字段”，从而在更新现有文档时不覆盖原有数据，同时确保新字段（如 `age`）在文档首次创建时被正确初始化。
在 MongoDB 中，当希望向文档添加一个仅在文档不存在时才初始化的字段（例如 age: 20），而对已存在的文档仅更新其他字段、不干扰该字段时，直接使用 $set 会导致所有匹配文档（包括已存在者）都被强制写入该字段——这往往不符合业务预期。此时，$setOnInsert 是专为此类场景设计的核心操作符。
$setOnInsert 的语义非常明确：仅当执行的是插入操作（即 upsert 触发了新文档创建）时，才设置指定字段；若匹配到已有文档并执行更新，则忽略该操作。它必须与 upsert: true 配合使用，且通常用于 findOneAndUpdate() 或 updateOne() 等更新方法中。
以下是一个典型示例，基于原始数据结构：
db.collection.findOneAndUpdate(
{ key: 1 }, // 查询条件：匹配 key 为 1 的文档
{
$setOnInsert: {
key: 1, // 注意：key 通常应由应用层保证唯一性，此处仅为示例完整性
name: "abc",
age: 20
}
},
{
upsert: true, // 启用 upsert：查无则插，有则更新（但 $setOnInsert 不生效）
returnDocument: "after" // MongoDB 4.2+ 推荐写法（替代已废弃的 returnOriginal: false）
}
)✅ 执行效果说明：
- 若数据库中不存在 { key: 1 } 的文档 → 执行插入，新文档将包含 key, name, age 字段；
- 若文档已存在（如原 { "key": 1, "name": "abc" }）→ 执行更新操作，但 age: 20 不会被写入或覆盖，原字段保持不变；
- 同时，其他 $set、$inc 等操作仍可并行使用（只要不在 $setOnInsert 中重复声明）。
⚠️ 关键注意事项：
- $setOnInsert 不会修改已有字段值，也无法用于条件性更新已有字段（如“若 age 不存在则设为 20”需改用 $set + $exists 查询，见下文补充）；
- 若需实现“如果字段不存在就添加，存在则跳过”（无论文档新旧），应使用 $set 配合查询条件：
db.collection.updateOne( { key: 1, age: { $exists: false } }, // 仅匹配 age 缺失的文档 { $set: { age: 20 } } ) - key 字段在 $setOnInsert 中重复赋值通常是冗余的（除非你依赖其作为插入时的默认值），实际中建议由 _id 或业务主键保证唯一性，避免逻辑冲突。
总结而言，$setOnInsert 是 MongoDB 中实现“安全初始化字段”的标准方案，适用于用户注册默认属性、订单初始状态、配置项兜底值等典型场景。合理搭配 upsert 和精准查询条件，即可在数据演进过程中兼顾兼容性与健壮性。
