插件（Plugins）的开发与使用

插件（Plugins）的基本概念

Mongoose插件是一种可复用的功能模块，能够为Schema添加额外的功能或修改现有行为。插件通过封装通用的逻辑，避免代码重复，使得Schema的功能扩展更加模块化和可维护。每个插件本质上是一个函数，接收schema和options作为参数，可以在schema上添加方法、静态方法、虚拟属性、中间件等。

// 一个简单的插件示例
function timestampPlugin(schema, options) {
  schema.add({ 
    createdAt: Date,
    updatedAt: Date 
  });

  schema.pre('save', function(next) {
    const now = new Date();
    this.updatedAt = now;
    if (!this.createdAt) {
      this.createdAt = now;
    }
    next();
  });
}

插件的开发方法

开发Mongoose插件需要遵循特定的模式。首先定义一个函数，该函数接受schema和可选的options参数。在函数体内，可以对schema进行各种操作：

1. 添加字段：使用schema.add()方法添加新字段
2. 定义方法：通过schema.methods添加实例方法
3. 定义静态方法：通过schema.statics添加静态方法
4. 添加中间件：使用pre和post钩子
5. 定义虚拟属性：通过schema.virtual()

function paginatePlugin(schema, options) {
  const defaultOptions = {
    perPage: 10,
    maxPerPage: 50
  };
  const opts = { ...defaultOptions, ...options };

  // 添加静态方法
  schema.statics.paginate = async function(query, page = 1, perPage = opts.perPage) {
    const skip = (page - 1) * perPage;
    const limit = Math.min(perPage, opts.maxPerPage);
    const [total, items] = await Promise.all([
      this.countDocuments(query),
      this.find(query).skip(skip).limit(limit)
    ]);
    return {
      total,
      page,
      perPage: limit,
      totalPages: Math.ceil(total / limit),
      items
    };
  };
}

插件的使用方式

使用插件非常简单，只需要在定义schema后调用plugin()方法即可。可以传递选项参数来自定义插件行为。

const mongoose = require('mongoose');
const { Schema } = mongoose;

const userSchema = new Schema({
  name: String,
  email: String
});

// 应用插件
userSchema.plugin(timestampPlugin);
userSchema.plugin(paginatePlugin, { maxPerPage: 30 });

const User = mongoose.model('User', userSchema);

// 使用插件添加的功能
async function getUsers(page) {
  return await User.paginate({}, page);
}

常用插件开发模式

1. 审计日志插件

记录文档的创建和修改时间，以及操作用户信息。

function auditLogPlugin(schema, options) {
  const userModel = options.userModel || 'User';
  
  schema.add({
    createdBy: { type: Schema.Types.ObjectId, ref: userModel },
    updatedBy: { type: Schema.Types.ObjectId, ref: userModel },
    createdAt: Date,
    updatedAt: Date
  });

  schema.pre('save', function(next) {
    const now = new Date();
    this.updatedAt = now;
    if (this.isNew) {
      this.createdAt = now;
      // 假设上下文中有当前用户信息
      if (this.$context && this.$context.userId) {
        this.createdBy = this.$context.userId;
      }
    }
    if (this.isModified() && this.$context && this.$context.userId) {
      this.updatedBy = this.$context.userId;
    }
    next();
  });
}

2. 软删除插件

实现软删除功能，而不是真正从数据库中删除文档。

function softDeletePlugin(schema, options) {
  const deletedAtField = options.deletedAtField || 'deletedAt';
  const isDeletedField = options.isDeletedField || 'isDeleted';
  
  schema.add({
    [deletedAtField]: Date,
    [isDeletedField]: { type: Boolean, default: false }
  });

  // 添加删除方法
  schema.methods.softDelete = function() {
    this[isDeletedField] = true;
    this[deletedAtField] = new Date();
    return this.save();
  };

  // 添加恢复方法
  schema.methods.restore = function() {
    this[isDeletedField] = false;
    this[deletedAtField] = undefined;
    return this.save();
  };

  // 修改查询行为，自动过滤已删除文档
  schema.pre(/^find/, function() {
    if (!this.getFilter()[isDeletedField]) {
      this.where({ [isDeletedField]: false });
    }
  });
}

高级插件技巧

1. 插件组合

多个插件可以组合使用，但需要注意执行顺序和可能的冲突。

const productSchema = new Schema({
  name: String,
  price: Number
});

productSchema.plugin(timestampPlugin);
productSchema.plugin(auditLogPlugin, { userModel: 'Admin' });
productSchema.plugin(softDeletePlugin);

2. 条件插件应用

可以根据环境或其他条件决定是否应用插件。

if (process.env.NODE_ENV === 'development') {
  const debugPlugin = require('./debug-plugin');
  userSchema.plugin(debugPlugin);
}

3. 插件依赖管理

当插件之间有依赖关系时，需要确保正确的加载顺序。

function dependentPlugin(schema, options) {
  // 检查是否已安装基础插件
  if (!schema.methods.baseMethod) {
    throw new Error('dependentPlugin requires basePlugin to be installed first');
  }
  // 插件实现...
}

实际应用案例

1. 多语言支持插件

为文档添加多语言字段支持。

function multilingualPlugin(schema, options) {
  const { fields = [], languages = ['en', 'zh'] } = options;

  fields.forEach(field => {
    const multilingualField = {};
    languages.forEach(lang => {
      multilingualField[lang] = schema.path(field).instance;
    });
    schema.add({ [field]: multilingualField });
    schema.remove(field);

    // 添加获取当前语言值的方法
    schema.method(`get${field.charAt(0).toUpperCase() + field.slice(1)}`, function(lang) {
      return this[field][lang] || this[field][languages[0]];
    });
  });
}

// 使用示例
const productSchema = new Schema({
  name: String,
  description: String
});

productSchema.plugin(multilingualPlugin, {
  fields: ['name', 'description'],
  languages: ['en', 'zh', 'ja']
});

2. 版本控制插件

实现文档的版本控制功能。

function versionControlPlugin(schema, options) {
  const versionSchema = new Schema({
    refId: Schema.Types.ObjectId,
    data: {},
    version: Number,
    modifiedBy: Schema.Types.ObjectId,
    modifiedAt: Date
  }, { timestamps: true });

  const VersionModel = mongoose.model(options.versionModel || 'Version', versionSchema);

  schema.pre('save', async function(next) {
    if (this.isModified()) {
      const versionData = this.toObject();
      delete versionData._id;
      delete versionData.__v;
      
      await VersionModel.create({
        refId: this._id,
        data: versionData,
        version: (await VersionModel.countDocuments({ refId: this._id })) + 1,
        modifiedBy: this.$context?.userId
      });
    }
    next();
  });

  schema.methods.getVersions = function() {
    return VersionModel.find({ refId: this._id }).sort('-version');
  };

  schema.statics.restoreVersion = async function(id, version) {
    const doc = await this.findById(id);
    const versionDoc = await VersionModel.findOne({ refId: id, version });
    if (!versionDoc) throw new Error('Version not found');
    
    doc.set(versionDoc.data);
    return doc.save();
  };
}

性能优化考虑

开发插件时需要考虑性能影响：

1. 避免不必要的中间件：只在必要时添加pre/post钩子
2. 批量操作优化：考虑updateMany等批量操作的场景
3. 索引管理：插件添加的字段可能需要索引
4. 查询优化：避免插件导致查询性能下降

function optimizedPlugin(schema) {
  // 只在必要时添加索引
  if (process.env.NODE_ENV === 'production') {
    schema.index({ updatedAt: -1 });
  }

  // 优化批量更新
  schema.pre('updateMany', function(next) {
    this.update({}, { $set: { updatedAt: new Date() } });
    next();
  });
}

测试插件的最佳实践

为插件编写测试是确保其可靠性的关键：

1. 隔离测试：单独测试插件功能
2. 多种场景：测试不同选项配置
3. 性能测试：确保不会引入性能问题
4. 与其他插件兼容性：测试与其他常用插件的组合

describe('timestampPlugin', () => {
  let TestModel;
  
  before(() => {
    const schema = new Schema({ name: String });
    schema.plugin(timestampPlugin);
    TestModel = mongoose.model('Test', schema);
  });

  it('should add createdAt and updatedAt fields', async () => {
    const doc = await TestModel.create({ name: 'test' });
    expect(doc.createdAt).to.be.instanceOf(Date);
    expect(doc.updatedAt).to.be.instanceOf(Date);
  });

  it('should update updatedAt on save', async () => {
    const doc = await TestModel.create({ name: 'test' });
    const originalUpdatedAt = doc.updatedAt;
    await new Promise(resolve => setTimeout(resolve, 10));
    doc.name = 'updated';
    await doc.save();
    expect(doc.updatedAt.getTime()).to.be.greaterThan(originalUpdatedAt.getTime());
  });
});

插件生态系统

Mongoose有一个丰富的插件生态系统，一些流行的插件包括：

1. mongoose-autopopulate：自动填充引用字段
2. mongoose-paginate-v2：分页功能
3. mongoose-unique-validator：唯一性验证
4. mongoose-lean-virtuals：在lean查询中包含虚拟字段

// 使用第三方插件的示例
const uniqueValidator = require('mongoose-unique-validator');

const userSchema = new Schema({
  email: { type: String, required: true, unique: true }
});

userSchema.plugin(uniqueValidator, { 
  message: 'Error, expected {PATH} to be unique.' 
});

自定义插件的高级模式

对于更复杂的场景，可以考虑以下高级模式：

1. 动态字段插件：根据配置动态添加字段
2. 状态机插件：实现文档状态转换
3. 权限控制插件：基于角色的字段级访问控制
4. 缓存插件：自动缓存查询结果

function stateMachinePlugin(schema, options) {
  const { field = 'status', states, transitions } = options;
  
  schema.add({ [field]: { type: String, default: states.initial } });

  schema.methods.canTransitionTo = function(newState) {
    return transitions[this[field]].includes(newState);
  };

  schema.methods.transitionTo = function(newState) {
    if (!this.canTransitionTo(newState)) {
      throw new Error(`Invalid transition from ${this[field]} to ${newState}`);
    }
    this[field] = newState;
    return this.save();
  };

  // 添加状态检查方法
  states.valid.forEach(state => {
    schema.methods[`is${state.charAt(0).toUpperCase() + state.slice(1)}`] = function() {
      return this[field] === state;
    };
  });
}

// 使用示例
const taskSchema = new Schema({
  title: String
});

taskSchema.plugin(stateMachinePlugin, {
  states: {
    initial: 'new',
    valid: ['new', 'inProgress', 'completed', 'archived']
  },
  transitions: {
    new: ['inProgress'],
    inProgress: ['completed', 'new'],
    completed: ['archived'],
    archived: []
  }
});