Mongoose

Mongoose 构造函数。

mongoose 模块的导出对象是此类的实例。大多数应用程序只会使用这一个实例。

示例

const mongoose = require('mongoose');
mongoose instanceof mongoose.Mongoose; // true

// Create a new Mongoose instance with its own `connect()`, `set()`, `model()`, etc.
const m = new mongoose.Mongoose();

Mongoose Aggregate 构造函数

Mongoose CastError 构造函数

Mongoose Collection 构造函数

Mongoose Connection 构造函数

公开连接状态以供用户使用

Mongoose Date SchemaType。

示例

const schema = new Schema({ test: Date });
schema.path('test') instanceof mongoose.Date; // true

Mongoose Decimal128 SchemaType。用于在模式中声明应为 128 位十进制浮点数 的路径。不要使用此方法创建新的 Decimal128 实例，而是使用 mongoose.Types.Decimal128。

示例

const vehicleSchema = new Schema({ fuelLevel: mongoose.Decimal128 });

Mongoose Document 构造函数。

Mongoose DocumentProvider 构造函数。Mongoose 用户不应该直接使用此函数

The MongooseError constructor.

Mongoose Mixed SchemaType。用于在模式中声明 Mongoose 的更改跟踪、转换和验证应忽略的路径。

示例

const schema = new Schema({ arbitrary: mongoose.Mixed });

Mongoose Model 构造函数。

Mongoose 构造函数

mongoose 模块的导出是此类的实例。

示例

const mongoose = require('mongoose');
const mongoose2 = new mongoose.Mongoose();

Mongoose Number SchemaType。用于在模式中声明 Mongoose 应转换为数字的路径。

示例

const schema = new Schema({ num: mongoose.Number });
// Equivalent to:
const schema = new Schema({ num: 'number' });

Mongoose ObjectId SchemaType。用于在模式中声明应为 MongoDB ObjectIds 的路径。不要使用此方法创建新的 ObjectId 实例，而是使用 mongoose.Types.ObjectId。

示例

const childSchema = new Schema({ parentId: mongoose.ObjectId });

Mongoose Query 构造函数。

公开连接状态以供用户使用

Mongoose Schema 构造函数

示例

const mongoose = require('mongoose');
const Schema = mongoose.Schema;
const CatSchema = new Schema(..);

Mongoose SchemaType 构造函数

用于模式类型选项的构造函数

各种 Mongoose SchemaTypes。

注意

为了向后兼容，它是 mongoose.Schema.Types 的别名。

各种 Mongoose 类型。

示例

const mongoose = require('mongoose');
const array = mongoose.Types.Array;

类型

• Array
• Buffer
• 嵌入
• DocumentArray
• Decimal128
• ObjectId
• Map
• Subdocument

使用对 ObjectId 类型的公开访问，我们可以按需构造 ID。

const ObjectId = mongoose.Types.ObjectId;
const id1 = new ObjectId;

Mongoose VirtualType 构造函数

打开默认的 Mongoose 连接。

示例

mongoose.connect('mongodb://user:[email protected]:port/database');

// replica sets
const uri = 'mongodb://user:[email protected]:port,anotherhost:port,yetanother:port/mydatabase';
mongoose.connect(uri);

// with options
mongoose.connect(uri, options);

// Using `await` throws "MongooseServerSelectionError: Server selection timed out after 30000 ms"
// if Mongoose can't connect.
const uri = 'mongodb://nonexistent.domain:27000';
await mongoose.connect(uri);

Mongoose 模块的默认连接。等效于 mongoose.connections[0]，查看 connections。

示例

const mongoose = require('mongoose');
mongoose.connect(...);
mongoose.connection.on('error', cb);

这是使用 mongoose.model 创建的每个模型默认使用的连接。

要创建新的连接，请使用 createConnection()。

包含与该 Mongoose 实例关联的所有 连接 的数组。默认情况下，有一个连接。调用 createConnection() 会将连接添加到此数组。

示例

const mongoose = require('mongoose');
mongoose.connections.length; // 1, just the default connection
mongoose.connections[0] === mongoose.connection; // true

mongoose.createConnection('mongodb://127.0.0.1:27017/test');
mongoose.connections.length; // 2

创建 Connection 实例。

每个 connection 实例映射到一个数据库。此方法在管理多个数据库连接时很有用。

传递的选项优先于连接字符串中包含的选项。

示例

// with mongodb:// URI
db = mongoose.createConnection('mongodb://user:[email protected]:port/database');

// and options
const opts = { db: { native_parser: true }}
db = mongoose.createConnection('mongodb://user:[email protected]:port/database', opts);

// replica sets
db = mongoose.createConnection('mongodb://user:[email protected]:port,anotherhost:port,yetanother:port/database');

// and options
const opts = { replset: { strategy: 'ping', rs_name: 'testSet' }}
db = mongoose.createConnection('mongodb://user:[email protected]:port,anotherhost:port,yetanother:port/database', opts);

// initialize now, connect later
db = mongoose.createConnection();
await db.openUri('mongodb://127.0.0.1:27017/database');

从默认连接中移除名为 name 的模型（如果存在）。您可以使用此函数清理在测试中创建的任何模型，以防止 OverwriteModelErrors。

等同于 mongoose.connection.deleteModel(name)。

示例

mongoose.model('User', new Schema({ name: String }));
console.log(mongoose.model('User')); // Model object
mongoose.deleteModel('User');
console.log(mongoose.model('User')); // undefined

// Usually useful in a Mocha `afterEach()` hook
afterEach(function() {
  mongoose.deleteModel(/.+/); // Delete every model
});

在所有连接上并行运行 .close()。

包含 get() 和 set() 的对象，其中包含此 Mongoose 实例用于与数据库通信的底层驱动程序。驱动程序是 Mongoose 特定的接口，定义了诸如 find() 之类的函数。

获取 mongoose 选项

示例

mongoose.get('test') // returns the 'test' value

如果给定值为 Mongoose ObjectId（使用 instanceof），或者给定值为 24 个字符的十六进制字符串（这是 ObjectId 最常用的字符串表示形式），则返回 true。

此函数类似于 isValidObjectId()，但要严格得多，因为 isValidObjectId() 将对 Mongoose 可以转换为 ObjectId 的任何值返回 true。这包括 Mongoose 文档、任何长度为 12 的字符串和任何数字。isObjectIdOrHexString() 仅对 ObjectId 实例或 24 个字符的十六进制字符串返回 true，并且将对数字、文档和长度为 12 的字符串返回 false。

示例

mongoose.isObjectIdOrHexString(new mongoose.Types.ObjectId()); // true
mongoose.isObjectIdOrHexString('62261a65d66c6be0a63c051f'); // true

mongoose.isObjectIdOrHexString('0123456789ab'); // false
mongoose.isObjectIdOrHexString(6); // false
mongoose.isObjectIdOrHexString(new User({ name: 'test' })); // false
mongoose.isObjectIdOrHexString({ test: 42 }); // false

如果 Mongoose 可以将给定值强制转换为 ObjectId，则返回 true，否则返回 false。

示例

mongoose.isValidObjectId(new mongoose.Types.ObjectId()); // true
mongoose.isValidObjectId('0123456789ab'); // true
mongoose.isValidObjectId(6); // true
mongoose.isValidObjectId(new User({ name: 'test' })); // true

mongoose.isValidObjectId({ test: 42 }); // false

定义或检索模型。

在 mongoose 实例上定义的模型可供同一 mongoose 实例创建的所有连接使用。

如果你使用相同的名称但不同的模式两次调用 mongoose.model()，你将收到 OverwriteModelError。如果你使用相同的名称和相同的模式调用 mongoose.model()，你将获得相同的模式。

示例

const mongoose = require('mongoose');

// define an Actor model with this mongoose instance
const schema = new Schema({ name: String });
mongoose.model('Actor', schema);

// create a new connection
const conn = mongoose.createConnection(..);

// create Actor model
const Actor = conn.model('Actor', schema);
conn.model('Actor') === Actor; // true
conn.model('Actor', schema) === Actor; // true, same schema
conn.model('Actor', schema, 'actors') === Actor; // true, same schema and collection name

// This throws an `OverwriteModelError` because the schema is different.
conn.model('Actor', new Schema({ name: String }));

当不传递 collection 参数时，Mongoose 使用模型名称。如果你不喜欢这种行为，要么传递一个集合名称，要么使用 mongoose.pluralize()，要么设置你的模式集合名称选项。

示例

const schema = new Schema({ name: String }, { collection: 'actor' });

// or

schema.set('collection', 'actor');

// or

const collectionName = 'actor';
const M = mongoose.model('Actor', schema, collectionName);

返回在此 Mongoose 实例上创建的模型名称数组。

注意

不包括使用 connection.model() 创建的模型的名称。

Mongoose 使用的 mquery 查询生成器。

Mongoose 使用此函数在设置 时间戳 时获取当前时间。你可以使用像 Sinon 这样的工具为测试模拟此函数。

接受一个对象并删除该对象中值为严格等于 undefined 的任何键。此函数对查询过滤器很有用，因为 Mongoose 将 TestModel.find({ name: undefined }) 视为 TestModel.find({ name: null })。

示例

const filter = { name: 'John', age: undefined, status: 'active' };
mongoose.omitUndefined(filter); // { name: 'John', status: 'active' }
filter; // { name: 'John', status: 'active' }

await UserModel.findOne(mongoose.omitUndefined(filter));

在 post() 中间件中使用此函数来替换结果

示例

schema.post('find', function(res) {
  // Normally you have to modify `res` in place. But with
  // `overwriteMiddlewarResult()`, you can make `find()` return a
  // completely different value.
  return mongoose.overwriteMiddlewareResult(res.filter(doc => !doc.isDeleted));
});

声明在所有模式上执行的全局插件。

等同于在你创建的每个模式上调用 .plugin(fn)。

围绕用于将集合名称变为复数的函数的 getter/setter。

通过将任何嵌套对象（其属性名称以 $ 开头）包装在 $eq 中来清理查询过滤器以防范 查询选择器注入攻击。

const obj = { username: 'val', pwd: { $ne: null } };
sanitizeFilter(obj);
obj; // { username: 'val', pwd: { $eq: { $ne: null } } });

设置 mongoose 选项

key 可以用作对象来一次设置多个选项。如果一个选项抛出错误，其他选项仍将被评估。

示例

mongoose.set('test', value) // sets the 'test' option to `value`

mongoose.set('debug', true) // enable logging collection methods + arguments to the console/file

mongoose.set('debug', function(collectionName, methodName, ...methodArgs) {}); // use custom function to log collection methods + arguments

mongoose.set({ debug: true, autoIndex: false }); // set multiple options at once

当前支持的选项是

• allowDiskUse：设置为 true 以默认情况下将所有聚合操作的 allowDiskUse 设置为 true。
• applyPluginsToChildSchemas：默认情况下为 true。设置为 false 以跳过将全局插件应用于子模式
• applyPluginsToDiscriminators：默认情况下为 false。设置为 true 以将全局插件应用于鉴别器模式。这通常没有必要，因为插件应用于基本模式，鉴别器会从基本模式复制所有中间件、方法、静态方法和属性。
• autoCreate：设置为 true 使 Mongoose 在使用 mongoose.model() 或 conn.model() 创建模型时自动调用 Model.createCollection()。这对于测试事务、更改流和其他需要集合存在的特性很有用。
• autoIndex：默认情况下为 true。设置为 false 以禁用与此 Mongoose 实例关联的所有模型的自动索引创建。
• bufferCommands：启用/禁用 mongoose 的所有连接和模型的缓冲机制
• bufferTimeoutMS：如果 bufferCommands 处于打开状态，则此选项设置 Mongoose 缓冲在抛出错误之前等待的最长时间。如果未指定，Mongoose 将使用 10000（10 秒）。
• cloneSchemas：默认情况下为 false。设置为 true 以在编译成模型之前 clone() 所有模式。
• debug：如果为 true，则将 Mongoose 发送到 MongoDB 的操作打印到控制台。如果传递了一个可写流，它将记录到该流，但不进行着色。如果传递了一个回调函数，它将接收集合名称、方法名称，以及传递给该方法的所有参数。例如，如果你想复制默认日志记录，你可以在回调中输出 Mongoose: ${collectionName}.${methodName}(${methodArgs.join(', ')})。
• id：如果为 true，则向所有模式添加 id 虚拟属性，除非在每个模式的基础上覆盖。
• timestamps.createdAt.immutable：默认情况下为 true。如果为 false，它将更改 createdAt 字段以使其 immutable: false，这意味着你可以更新 createdAt
• maxTimeMS：如果设置，则将 maxTimeMS 附加到每个查询
• objectIdGetter：默认情况下为 true。Mongoose 向 MongoDB ObjectId 添加了一个名为 _id 的 getter，该 getter 返回 this，方便与 populate 一起使用。将此设置为 false 以删除 getter。
• overwriteModels：设置为 true 以默认情况下在调用 mongoose.model() 时覆盖同名模型，而不是抛出 OverwriteModelError。
• returnOriginal：如果为 false，则将 findOneAndUpdate()、findByIdAndUpdate 和 findOneAndReplace() 的默认 returnOriginal 选项更改为 false。这等同于默认情况下将 findOneAndX() 调用的 new 选项设置为 true。阅读我们的 findOneAndUpdate() 教程 以获取更多信息。
• runValidators：默认情况下为 false。设置为 true 以默认情况下为所有验证器启用 更新验证器。
• sanitizeFilter：默认情况下为 false。设置为 true 以通过将任何嵌套对象（其属性名称以 $ 开头）包装在 $eq 中来启用 查询过滤器清理 以防范查询选择器注入攻击。
• selectPopulatedPaths：默认情况下为 true。设置为 false 以选择退出 Mongoose 将你 populate() 的所有字段添加到你的 select() 中。模式级选项 selectPopulatedPaths 会覆盖此选项。
• strict：默认情况下为 true，可以是 false、true 或 'throw'。设置模式的默认严格模式。
• strictQuery：默认情况下为 false。可以是 false、true 或 'throw'。设置模式的默认 strictQuery 模式。
• toJSON：默认情况下为 { transform: true, flattenDecimals: true }。将默认对象覆盖为 toJSON()，用于确定 Mongoose 文档如何被 JSON.stringify() 序列化
• toObject：默认情况下为 { transform: true, flattenDecimals: true }。将默认对象覆盖为 toObject()

覆盖此 Mongoose 实例使用的当前驱动程序。驱动程序是 Mongoose 特定的接口，定义了诸如 find() 之类的函数。

在 pre() 中间件中使用此函数以跳过调用包装函数。

示例

schema.pre('save', function() {
  // Will skip executing `save()`, but will execute post hooks as if
  // `save()` had executed with the result `{ matchedCount: 0 }`
  return mongoose.skipMiddlewareFunction({ matchedCount: 0 });
});

需要 MongoDB >= 3.6.0。 启动 MongoDB 会话 以获得因果一致性、可重试写入 和 事务 等好处。

调用 mongoose.startSession() 等同于调用 mongoose.connection.startSession()。会话的作用域是连接，因此调用 mongoose.startSession() 会在 默认 mongoose 连接 上启动一个会话。

同步与此连接注册的所有模型的索引。

告诉 sanitizeFilter() 在过滤掉潜在的 查询选择器注入攻击 时跳过给定对象。当你有一个已知的查询选择器要使用时，使用此方法。

const obj = { username: 'val', pwd: trusted({ $type: 'string', $eq: 'my secret' }) };
sanitizeFilter(obj);

// Note that `sanitizeFilter()` did not add `$eq` around `$type`.
obj; // { username: 'val', pwd: { $type: 'string', $eq: 'my secret' } });

Mongoose 版本

示例

console.log(mongoose.version); // '5.x.x'