MongoDB 中 returnNewDocument 不存在，正确参数是 returnDocument，值为 "before" 或 "after"，仅 findOneAndUpdate() 支持，用于原子性返回更新前/后的完整文档；updateOne() 等纯写操作不返回文档。
直接说结论：MongoDB 原生 Shell 和官方驱动中没有 returnNewDocument 这个参数名，它实际对应的是 returnDocument（仅用于 findOneAndUpdate()），且值必须是 "before" 或 "after"。
findOneAndUpdate() 中的 returnDocument 选项怎么用
只有 findOneAndUpdate() 支持在一次操作中返回文档快照，updateOne()、updateMany()、replaceOne() 都不返回文档内容，只返回操作结果对象（含 matchedCount、modifiedCount 等）。
关键点：
-
returnDocument: "after"表示返回更新后的完整文档（含所有字段，不只是被修改的部分） -
returnDocument: "before"返回更新前的原始文档 - 该选项必须配合
projection使用才能控制返回字段，否则默认返回整个文档 - 如果不传
returnDocument，默认行为是"before"
示例：
db.users.findOneAndUpdate(
{ _id: ObjectId("...") },
{ $inc: { loginCount: 1 } },
{ returnDocument: "after", projection: { _id: 1, loginCount: 1 } }
)
为什么 updateOne() 不返回文档，而 findOneAndUpdate() 可以
语义差异决定行为：
-
updateOne()是纯写操作，设计目标就是“改数据”，不带读语义，所以不返回文档，响应更快、资源开销更小 -
findOneAndUpdate()是原子性“查找 + 更新 + 返回”三合一操作，本质是带更新的查询，因此支持返回快照 - 如果你在
updateOne()后立刻find()，并发场景下可能读到其他写入覆盖后的值，不是原子保证
常见错误：误以为 updateOne(..., { returnNewDocument: true }) 有效 —— 这会静默忽略该参数，不报错但也不生效。
Go mgo/v2 或 mongo-go-driver 中的等效写法
不同驱动命名略有差异，但逻辑一致：
- mgo（已归档，但仍有项目在用）：
ReturnNew: true对应returnDocument: "after" - mongo-go-driver（推荐）：
options.FindOneAndUpdate().SetReturnDocument(options.After) - Node.js MongoDB Driver：
{ returnDocument: "after" }直接传入第三参数
注意：所有驱动都要求查询条件能唯一命中一个文档（如用 _id），否则行为未定义 —— 即使你写了 returnDocument: "after"，也可能返回任意一个匹配文档，无法预测。
容易被忽略的坑：upsert + returnDocument 组合
当 upsert: true 且没找到匹配文档时：
-
returnDocument: "after"→ 返回插入后的新文档（含自动生成的_id） -
returnDocument: "before"→ 返回null（因为原文档不存在） - 务必检查返回值是否为
null，否则可能 panic 或逻辑出错
这个组合在实现“计数器初始化 + 自增”或“用户首次登录创建档案”时很常用，但很多人忘了处理 null 分支。
