如何在 Mongoose 中使用 `findOneAndUpdate()`

¥How to Use findOneAndUpdate() in Mongoose

Mongoose 中的 findOneAndUpdate() 函数具有广泛的用例。你应该尽可能使用 save() 来更新文档，更好的 validation 和中间件支持。但是，在某些情况下你需要使用 findOneAndUpdate()。在本教程中，你将了解如何使用 findOneAndUpdate()，并了解何时需要使用它。

¥The findOneAndUpdate() function in Mongoose has a wide variety of use cases. You should use save() to update documents where possible, for better validation and middleware support. However, there are some cases where you need to use findOneAndUpdate(). In this tutorial, you'll see how to use findOneAndUpdate(), and learn when you need to use it.

入门

¥Getting Started

顾名思义，findOneAndUpdate() 查找与给定 filter 匹配的第一个文档，应用 update，然后返回该文档。findOneAndUpdate() 函数具有以下签名：

¥As the name implies, findOneAndUpdate() finds the first document that matches a given filter, applies an update, and returns the document. The findOneAndUpdate() function has the following signature:

function findOneAndUpdate(filter, update, options) {}

默认情况下，findOneAndUpdate() 返回应用 update 之前的文档。在下面的示例中，doc 最初仅具有 name 和 _id 属性。findOneAndUpdate() 添加了 age 属性，但 findOneAndUpdate() 的结果没有 age 属性。

¥By default, findOneAndUpdate() returns the document as it was before update was applied. In the following example, doc initially only has name and _id properties. findOneAndUpdate() adds an age property, but the result of findOneAndUpdate() does not have an age property.

const Character = mongoose.model('Character', new mongoose.Schema({
  name: String,
  age: Number
}));

const _id = new mongoose.Types.ObjectId('0'.repeat(24));
let doc = await Character.create({ _id, name: 'Jean-Luc Picard' });
doc; // { name: 'Jean-Luc Picard', _id: ObjectId('000000000000000000000000') }

const filter = { name: 'Jean-Luc Picard' };
const update = { age: 59 };

// The result of `findOneAndUpdate()` is the document _before_ `update` was applied
doc = await Character.findOneAndUpdate(filter, update);
doc; // { name: 'Jean-Luc Picard', _id: ObjectId('000000000000000000000000') }

doc = await Character.findOne(filter);
doc.age; // 59

你应该将 new 选项设置为 true，以便在应用 update 后返回文档。

¥You should set the new option to true to return the document after update was applied.

const filter = { name: 'Jean-Luc Picard' };
const update = { age: 59 };

// `doc` is the document _after_ `update` was applied because of
// `new: true`
const doc = await Character.findOneAndUpdate(filter, update, {
  new: true
});
doc.name; // 'Jean-Luc Picard'
doc.age; // 59

Mongoose 的 findOneAndUpdate() 与 MongoDB Node.js 驱动程序的 findOneAndUpdate() 略有不同，因为它返回文档本身，而不是结果对象。

¥Mongoose's findOneAndUpdate() is slightly different from the MongoDB Node.js driver's findOneAndUpdate() because it returns the document itself, not a result object.

作为 new 选项的替代方案，你还可以使用 returnOriginal 选项。returnOriginal: false 相当于 new: true。returnOriginal 选项的存在是为了与具有相同选项的 MongoDB Node.js 驱动程序的 findOneAndUpdate() 保持一致。

¥As an alternative to the new option, you can also use the returnOriginal option. returnOriginal: false is equivalent to new: true. The returnOriginal option exists for consistency with the the MongoDB Node.js driver's findOneAndUpdate(), which has the same option.

const filter = { name: 'Jean-Luc Picard' };
const update = { age: 59 };

// `doc` is the document _after_ `update` was applied because of
// `returnOriginal: false`
const doc = await Character.findOneAndUpdate(filter, update, {
  returnOriginal: false
});
doc.name; // 'Jean-Luc Picard'
doc.age; // 59

原子更新

¥Atomic Updates

未索引的更新插入、findOneAndUpdate() 是原子的除外。这意味着你可以假设文档在 MongoDB 找到文档和更新文档之间不会发生更改，除非你正在执行 upsert。

¥With the exception of an unindexed upsert, findOneAndUpdate() is atomic. That means you can assume the document doesn't change between when MongoDB finds the document and when it updates the document, unless you're doing an upsert.

例如，如果你使用 save() 更新文档，则在使用 findOne() 加载文档和使用 save() 保存文档之间，MongoDB 中的文档可能会发生更改，如下所示。对于许多用例来说，save() 竞争条件不是问题。但如果需要，你可以使用 findOneAndUpdate()（或 transactions）来解决这个问题。

¥For example, if you're using save() to update a document, the document can change in MongoDB in between when you load the document using findOne() and when you save the document using save() as show below. For many use cases, the save() race condition is a non-issue. But you can work around it with findOneAndUpdate() (or transactions) if you need to.

const filter = { name: 'Jean-Luc Picard' };
const update = { age: 59 };

let doc = await Character.findOne({ name: 'Jean-Luc Picard' });

// Document changed in MongoDB, but not in Mongoose
await Character.updateOne(filter, { name: 'Will Riker' });

// This will update `doc` age to `59`, even though the doc changed.
doc.age = update.age;
await doc.save();

doc = await Character.findOne();
doc.name; // Will Riker
doc.age; // 59

更新插入

¥Upsert

使用 upsert 选项，你可以将 findOneAndUpdate() 用作 find-and-upsert 操作。如果 upsert 找到与 filter 匹配的文档，则其行为类似于正常的 findOneAndUpdate()。但是，如果没有文档与 filter 匹配，MongoDB 将通过组合 filter 和 update 来插入一个文档，如下所示。

¥Using the upsert option, you can use findOneAndUpdate() as a find-and-upsert operation. An upsert behaves like a normal findOneAndUpdate() if it finds a document that matches filter. But, if no document matches filter, MongoDB will insert one by combining filter and update as shown below.

const filter = { name: 'Will Riker' };
const update = { age: 29 };

await Character.countDocuments(filter); // 0

const doc = await Character.findOneAndUpdate(filter, update, {
  new: true,
  upsert: true // Make this update into an upsert
});
doc.name; // Will Riker
doc.age; // 29

The `includeResultMetadata` Option

Mongoose 默认转换 findOneAndUpdate() 的结果：它返回更新后的文档。这使得检查文档是否被更新插入变得困难。为了获取更新的文档并检查 MongoDB 是否在同一操作中更新插入了新文档，你可以设置 includeResultMetadata 标志以使 Mongoose 从 MongoDB 返回原始结果。

¥Mongoose transforms the result of findOneAndUpdate() by default: it returns the updated document. That makes it difficult to check whether a document was upserted or not. In order to get the updated document and check whether MongoDB upserted a new document in the same operation, you can set the includeResultMetadata flag to make Mongoose return the raw result from MongoDB.

const filter = { name: 'Will Riker' };
const update = { age: 29 };

await Character.countDocuments(filter); // 0

const res = await Character.findOneAndUpdate(filter, update, {
  new: true,
  upsert: true,
  // Return additional properties about the operation, not just the document
  includeResultMetadata: true
});

res.value instanceof Character; // true
// The below property will be `false` if MongoDB upserted a new
// document, and `true` if MongoDB updated an existing object.
res.lastErrorObject.updatedExisting; // false

上面示例中的 res 对象如下所示：

¥Here's what the res object from the above example looks like:

{ lastErrorObject:
   { n: 1,
     updatedExisting: false,
     upserted: 5e6a9e5ec6e44398ae2ac16a },
  value:
   { _id: 5e6a9e5ec6e44398ae2ac16a,
     name: 'Will Riker',
     __v: 0,
     age: 29 },
  ok: 1 }

更新鉴别器密钥

¥Updating Discriminator Keys

默认情况下，Mongoose 会阻止使用 findOneAndUpdate() 更新鉴别键。例如，假设你有以下判别器模型。

¥Mongoose prevents updating the discriminator key using findOneAndUpdate() by default. For example, suppose you have the following discriminator models.

const eventSchema = new mongoose.Schema({ time: Date });
const Event = db.model('Event', eventSchema);

const ClickedLinkEvent = Event.discriminator(
  'ClickedLink',
  new mongoose.Schema({ url: String })
);

const SignedUpEvent = Event.discriminator(
  'SignedUp',
  new mongoose.Schema({ username: String })
);

如果设置了 __t，Mongoose 将从 update 参数中删除 __t（默认鉴别键）。这是为了防止无意中更新鉴别器密钥；例如，如果你将不受信任的用户输入传递给 update 参数。但是，你可以通过将 overwriteDiscriminatorKey 选项设置为 true 来告诉 Mongoose 允许更新鉴别器密钥，如下所示。

¥Mongoose will remove __t (the default discriminator key) from the update parameter, if __t is set. This is to prevent unintentional updates to the discriminator key; for example, if you're passing untrusted user input to the update parameter. However, you can tell Mongoose to allow updating the discriminator key by setting the overwriteDiscriminatorKey option to true as shown below.

let event = new ClickedLinkEvent({ time: Date.now(), url: 'google.com' });
await event.save();

event = await ClickedLinkEvent.findByIdAndUpdate(
  event._id,
  { __t: 'SignedUp' },
  { overwriteDiscriminatorKey: true, new: true }
);
event.__t; // 'SignedUp', updated discriminator key

如何在 Mongoose 中使用 findOneAndUpdate()

入门

原子更新

更新插入

The includeResultMetadata Option

更新鉴别器密钥

如何在 Mongoose 中使用 `findOneAndUpdate()`

The `includeResultMetadata` Option