MongoDB Schema迁移最佳实践及规范操作技术问询

核心设计原则 #

MongoDB的Schema迁移目标和SQL数据库一致，核心要求为：迁移逻辑与业务代码解耦、可版本化、可追溯、可回滚、支持幂等执行（重复执行不会产生异常结果）。

主流迁移实现模式 #

MongoDB不需要把所有集合、索引创建逻辑耦合在业务代码中，有两种成熟的迁移模式可供选择：

1. 独立脚本迁移（类SQL的.sql脚本方案） #

和你熟悉的SQL脚本执行逻辑完全一致，可以编写独立的.js迁移脚本，通过MongoDB原生的mongosh客户端直接执行，完全和业务代码解耦。
示例脚本（按「时间戳+功能」命名，方便版本排序）：

// 20240520_create_user_collection.js
// 创建带校验规则的users集合
db.createCollection("users", {
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["name", "email"],
      properties: {
        name: { bsonType: "string" },
        email: { bsonType: "string", pattern: "^\\S+@\\S+\\.\\S+$" }
      }
    }
  }
})
// 创建邮箱唯一索引
db.users.createIndex({ email: 1 }, { unique: true })

执行命令：
mongosh "mongodb://数据库连接地址/目标库名" 20240520_create_user_collection.js
这种模式适合生产环境大版本迭代、涉及批量数据迁移/清洗的场景，运维/DB可以独立管控执行流程，和业务发布完全解耦。

2. 应用层自动迁移（代码内置方案） #

把迁移逻辑写在业务代码中，应用启动时自动检测当前Schema版本，执行未运行过的迁移步骤。
该模式适合小迭代、快速开发的内部项目、索引/集合的轻量变更场景，不需要单独走运维发布流程。注意必须单独维护schema_migrations集合记录已执行的迁移版本，避免重复执行：

// 查询当前已执行的最新迁移版本
const lastMigrationVersion = await db.schema_migrations.findOne().version
if (lastMigrationVersion < 20240520) {
  // 执行对应版本的迁移逻辑
  await db.users.createIndex({ phone: 1 })
  // 更新迁移版本记录
  await db.schema_migrations.updateOne({}, { $set: { version: 20240520 } })
}

通用推荐规范 #

• 所有迁移脚本必须按时间戳+功能描述命名，比如20240520_add_phone_index_to_users.js，方便排序和追溯变更
• 所有迁移逻辑必须保证幂等性：执行前先判断操作对象是否存在，比如创建索引前先用db.users.getIndexes()判断索引是否已经存在，避免重复执行报错
• 涉及数据修改/删除的迁移必须提前编写回滚脚本，执行前先做全量数据备份
• 生产环境禁止直接执行未测试的迁移脚本，必须先在测试/预发环境验证执行结果和性能影响（尤其大数据量下建索引建议加background: true参数，避免锁库影响业务）
• 如果团队使用CI/CD流程，可以把迁移脚本的执行集成到发布流水线，按版本自动执行，不需要人工干预

创建集合、索引等操作不需要全部写在业务代码中，可以根据团队的流程选择对应模式：如果追求和业务解耦、运维独立管控，优先选择独立脚本模式；如果是小项目追求开发效率，选择应用层内置迁移即可。

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