MongoDB 中 returnNewDocument 不存在，正确参数是 returnDocument，值为 "before" 或 "after"，仅 findOneAndUpdate() 支持，用于原子性返回更新前/后的完整文档；updateOne() 等纯写操作不返回文档。
先说一个明确的结论：如果你在 MongoDB 的文档里或者代码里搜索 returnNewDocument 这个参数，那大概率是找不到了。正确的参数名是 returnDocument，而且它只服务于 findOneAndUpdate() 这个方法，它的值只能是 "before" 或 "after"。
findOneAndUpdate() 中的 returnDocument 选项怎么用
在 MongoDB 的操作里，想一次操作既更新数据又拿到文档快照，findOneAndUpdate() 是唯一的选择。像 updateOne()、updateMany() 这类纯更新操作，它们的返回值只告诉你“匹配了多少条”、“修改了多少条”，不会包含文档内容本身。
这里有几个关键细节需要把握：
- 当你设置
returnDocument: "after"，返回的是更新完成后，包含所有字段的完整新文档，而不仅仅是那些被修改过的字段。 - 如果设置成
returnDocument: "before"，返回的则是更新前的原始文档状态。 - 这个选项必须和
projection参数配合使用，才能控制返回哪些字段。如果不指定projection，默认就会把整个文档都返回给你。 - 另外，如果你不传
returnDocument参数，它的默认行为是"before"，也就是返回更新前的文档。
来看一个具体的例子：
db.users.findOneAndUpdate(
{ _id: ObjectId("...") },
{ $inc: { loginCount: 1 } },
{ returnDocument: "after", projection: { _id: 1, loginCount: 1 } })
为什么 updateOne() 不返回文档，而 findOneAndUpdate() 可以
这背后的原因，其实是 MongoDB 对不同操作语义的精心设计。
updateOne()被定位为一个纯粹的“写操作”。它的核心任务就是修改数据，不承担“读”的职责。因此，它不返回文档内容，这种设计让它的响应速度更快，消耗的资源也更少。- 而
findOneAndUpdate()则是一个原子性的复合操作，本质上是“查找 + 更新 + 返回”三步合一。正因为它的设计里包含了“查找”，所以自然支持返回文档快照。 - 这里有个常见的误区：有人试图在
updateOne()后面立刻接一个find()来获取更新后的值。这在并发场景下是有风险的，因为你可能读到被其他写入操作覆盖后的新值，无法保证原子性。
需要警惕的是，如果你错误地在 updateOne() 的参数里写上 { returnNewDocument: true }，MongoDB 并不会报错，它会直接忽略这个无效参数，导致你的代码逻辑无法按预期生效。
Go mgo/v2 或 mongo-go-driver 中的等效写法
在不同的官方驱动里，这个参数的命名可能略有不同，但核心逻辑是完全一致的：
- 在已经归档的旧版 Go 驱动 mgo 中（很多老项目还在用），对应的参数是
ReturnNew: true，效果等同于returnDocument: "after"。 - 在官方推荐的 mongo-go-driver 中，写法是
options.FindOneAndUpdate().SetReturnDocument(options.After)。 - 在 Node.js 驱动中，则可以直接在第三个参数对象里传入
{ returnDocument: "after" }。
无论使用哪个驱动，有一个前提至关重要：你的查询条件必须能唯一确定一个文档（比如使用 _id）。否则，即使你指定了 returnDocument: "after"，返回的也可能是任意一个匹配的文档，结果无法预测。
容易被忽略的坑：upsert + returnDocument 组合
当你在操作中同时使用 upsert: true（找不到则插入）和 returnDocument 时，有一个边界情况很容易被遗漏。
- 如果文档不存在，最终执行了插入操作：此时
returnDocument: "after"会返回这个新插入的文档（包含自动生成的_id）。 - 同样是文档不存在并执行了插入：如果设置的是
returnDocument: "before"，由于“更新前”的文档根本不存在，返回值会是null。
这个组合在实现“计数器初始化并自增”或“用户首次登录时自动创建档案”这类功能时非常有用。但很多开发者会忘记处理返回 null 的情况，这可能导致程序 panic 或后续的业务逻辑出错。务必记得在代码中做好判空处理。
