updateOne正确写法：首参数filter必须为匹配对象（如{status:{$eq:"pending"}}），次参数update须带操作符（如{$set:{name:"new"}}）；upsert需显式启用，插入时filter字段必存，$setOnInsert仅插入生效。
updateOne 里怎么写条件和更新内容才不白跑
条件更新失败，八成是 filter 和 update 写反了，或者字段名拼错。MongoDB 的 updateOne 要求第一个参数是匹配条件（必须是对象），第二个才是更新操作符（比如 $set、$inc）。不是“查出来再改”，而是靠原子操作一步到位。
常见错误现象：matchedCount: 0 却以为数据该被改到；或误把 { name: "a" } 当成更新内容，结果删光字段。
-
filter必须用严格相等或操作符（如{ status: { $eq: "pending" } }），不能传字符串或数组 - 更新内容必须带操作符：直接写
{ name: "new" }会报错，得写{ $set: { name: "new" } } - 如果想只更新存在字段、避免新增字段，用
$setOnInsert配合 upsert，而不是裸$set
upsert 是不是等于“有就更新、没就插入”
不是自动的“智能合并”。upsert 只保证：当 filter 没匹配到文档时，用 filter + update 合并生成一条新文档——但这个“合并”不识别字段语义，只是浅层对象展开。
使用场景：幂等写入（如用户配置初始化）、事件去重写入（按 event_id 更新或创建）。
- 开启 upsert 要显式加
{ upsert: true }，默认是false - 新插入的文档 =
filter中的键值 +update中$set等操作符修改的字段；filter里的字段一定会进新文档，哪怕你没在$set里提它 - 如果
filter是{ _id: ObjectId("...") }，那 upsert 插入的就是这条_id，不会自增或重生成
更新时字段不存在，$set 和 $setOnInsert 行为差在哪
区别在于“仅插入时生效”。$set 无论更新还是插入都执行；$setOnInsert 只在 upsert 触发插入动作时才写入，更新已有文档时完全忽略它。
性能影响：几乎无差别；但逻辑上错用会导致数据不一致——比如你想给新用户设默认头像，却用了 $set，老用户头像就被强制覆盖了。
- 初始化字段（如
createdAt、status默认值）必须用$setOnInsert -
$set适合业务态更新（如lastLoginAt、score），每次都要刷 - 不要混用：同一个字段既用
$set又用$setOnInsert，MongoDB 不报错，但行为取决于哪条先执行（顺序由 driver 决定，不可靠）
为什么 updateOne 有时返回 matchedCount 0 但 modifiedCount 1
这是 upsert 开启后的正常表现：说明没找到匹配文档，但成功插入了一条。MongoDB 把“插入”算作一次“修改”，所以 modifiedCount 是 1，而 matchedCount 是 0。
容易踩的坑：前端或监控只看 matchedCount > 0 就认为“更新成功”，结果漏掉 upsert 场景，误判逻辑分支。
- 判断是否真做了更新，优先看
result.upsertedId是否存在，而不是matchedCount - 调试时打印完整
result，尤其注意acknowledged（是否写入确认）、upsertedCount（插入了几条） - Driver 版本差异：Node.js 4.x+ 的
updateOne返回对象结构统一，但旧版 Python PyMongo 可能用不同字段名，别硬背字段
最常被忽略的是 filter 和 update 的语义边界——它不帮你做“如果字段为空才设默认值”这种逻辑，所有条件判断得提前在应用层做完。MongoDB 只忠实地执行你写的操作符，不多猜，也不补救。
