必须显式设置 returndocument: 'after' 才能返回更新后的文档，因其默认值为 'before'，静默返回旧快照；mongoose 需用 new: true 或 returndocument: 'after'，且并发下不可用 updateone + findone 替代。

必须显式设置 returnDocument: 'after'，否则默认返回更新前的文档

findOneAndUpdate 为什么默认不返回新值

findOneAndUpdate() 的 returnDocument 选项默认值是 'before'，不是 'after'。很多人写了更新逻辑却拿不到新数据，卡在这一步——它不报错，也不提示，只是静默返回旧快照。

• returnDocument: 'before'（默认）→ 返回匹配到的原始文档，哪怕你刚用 $set 改了字段
• returnDocument: 'after' → 返回应用更新后、完整渲染过的文档（含所有字段，不只是被改的部分）
• 别写 returnNewDocument: true —— 这个参数名不存在，驱动会忽略它，且不报错

如何确保拿到更新后的完整文档

除了 returnDocument: 'after'，还要注意投影控制和字段一致性。直接返回整个文档可能带出你不想要的字段（比如 _id、__v），或漏掉计算字段（如 $addFields 后的结果）。

mongodb-query

用于调试和故障排查，查询MongoDB数据库。用户需要时可以： (1) 列出所有数据库； (2) 列出数据库中的集合； (3) 执行MongoDB查询或命令。

下载

• 用 projection 显式指定要返回的字段，例如 { _id: 1, status: 1, updatedAt: 1 }
• 如果用了聚合管道更新（如 $set + $cond），projection 仍生效，但不能过滤掉管道中新生成的字段
• 不要依赖 upsert: true 时的 value 字段：插入新文档时 value 是完整新文档；但若匹配失败且 upsert: false，result.value 就是 null

并发场景下，为什么不能用 updateOne + findOne 组合

看似省事的两步写法，在真实服务中极易出错。MongoDB 不保证这两步之间的原子性，中间可能被其他请求插队修改。

• 请求 A 执行 updateOne 成功，但还没来得及 findOne
• 请求 B 同时执行另一次 updateOne，覆盖了同一文档
• 请求 A 的 findOne 拿到的是请求 B 写入的结果，而非自己刚设的值
• 典型后果：订单状态显示“已处理”，实际仍是“待处理”；库存扣减后回显余量错误

容易被忽略的细节：Mongoose 与原生驱动行为差异

Mongoose 的 findOneAndUpdate() 默认不返回新文档，且早期版本甚至默认返回 undefined，必须手动开启选项。

• 原生 MongoDB Driver：必须传 { returnDocument: 'after' }
• Mongoose：需额外加 new: true（等价于 returnDocument: 'after'），且从 v7 起该选项已弃用，推荐统一用 returnDocument
• Mongoose 中 lean() 可减少实例化开销，但不影响 returnDocument 行为
• 回调风格写法里，data 参数默认是旧文档；Promise 风格下，result.value 才是目标字段

真正关键的不是“能不能返回”，而是“返回的到底是不是你刚写的那个值”。只要没设 returnDocument: 'after'，就等于没回显。