MongoDB结合Mongoose如何同步旧文档带默认值的Schema变更

实现逻辑 #

不需要执行提前批量update做全量数据迁移，利用Mongoose本身的文档生命周期钩子，在存量数据从数据库加载到运行时的瞬间，自动按照Schema定义递归补全缺失字段的默认值即可，补全的值仅在运行时生效，只有文档被主动save时才会持久化到库，实现零停机惰性迁移。

第一步：给所有Schema字段明确定义默认值 #

不管是顶层字段、嵌套对象字段还是数组字段，新增字段时直接在Schema定义中配置default规则，原有字段缺失默认值的补上即可，示例修改如下：

const todoSchema = new mongoose.Schema({
  title: {
    type: String,
    required: true,
  },
  description: {
    type: String,
    required: true,
  },
  by: {
    type: String,
    required: true,
    default: "system" // 替换为业务实际需要的默认值
  },
  // 后续新增嵌套Schema直接按相同规则写default即可，示例：
  // extra: {
  //   type: new mongoose.Schema({
  //     priority: { type: Number, default: 0 },
  //     archived: { type: Boolean, default: false }
  //   }),
  //   default: () => ({})
  // }
});

第二步：注册init生命周期钩子自动补值 #

init是Mongoose将MongoDB返回的原生BSON文档转换为Mongoose Document实例时触发的第一个钩子，这个阶段处理不会触发任何额外数据库操作，写一个通用递归逻辑即可自动适配所有层级的Schema字段，不需要每次Schema变更都修改适配代码：

/**
 * 递归按照Schema定义补全文档缺失的默认值
 * @param doc 文档原始数据对象
 * @param schemaPaths Mongoose Schema的路径映射表
 */
function applyDefaultsRecursive(doc: Record<string, any>, schemaPaths: Record<string, mongoose.SchemaType>) {
  Object.entries(schemaPaths).forEach(([path, schemaType]) => {
    // 跳过内部_id、Mongoose私有字段
    if (path === '_id' || path.startsWith('$')) return;

    // 处理嵌套文档类型
    if (schemaType.instance === 'Embedded' && (schemaType as any).schema) {
      if (!Array.isArray(doc[path]) && !doc[path]) doc[path] = {};
      // 嵌套数组场景遍历每一项补值
      if (Array.isArray(doc[path])) {
        doc[path].forEach(item => applyDefaultsRecursive(item, (schemaType as any).schema.paths))
      } else {
        applyDefaultsRecursive(doc[path], (schemaType as any).schema.paths);
      }
      return;
    }

    // 缺失字段直接赋值默认值
    if (doc[path] === undefined) {
      const defaultVal = schemaType.defaultValue;
      doc[path] = typeof defaultVal === 'function' ? defaultVal() : defaultVal;
    }
  });
}

// 注册前置init钩子，所有文档加载时自动执行补值
todoSchema.pre('init', function (next) {
  applyDefaultsRecursive(this._doc, todoSchema.paths);
  next();
});

方案特性 #

• 零迁移成本：不需要提前跑全量update脚本，上线即生效，不会因为存量数据量大导致锁库、业务停机
• 自动适配后续Schema变更：后续新增任意层级的字段，只要在Schema中配置好default值，不需要修改适配逻辑，旧文档加载时会自动补值
• 无额外性能开销：补值逻辑全同步执行在内存中，没有额外数据库请求；补全的默认值不会主动写回数据库，只有文档被业务逻辑主动save时才会持久化，实现惰性迁移
• 业务无感知：上层CRUD逻辑完全不需要修改，和原有写法保持一致

注意事项 #

• 用lean()方法查询时，Mongoose不会实例化Document对象，不会触发init钩子，这类查询如果需要补默认值，需要在结果返回后手动调用applyDefaultsRecursive处理，或者核心业务查询避免使用lean
• 不要在init钩子中写异步逻辑、数据库查询逻辑，会拖慢所有查询的响应速度，默认值尽量通过同步逻辑计算
• 不要在钩子中直接修改this上的属性，直接操作内部_doc属性可以避免触发Mongoose的变更追踪，减少不必要的脏字段标记

内容的提问来源于stack exchange，提问作者Mr X