Spring Boot中Mongock迁移文件类与集合名变更的处理方案咨询

我有一个基于Spring Boot的应用，使用Mongock与MongoDB。最近进行了大规模重构，修改了许多类名和集合名：

重构前的实体类：

@Document("foo")
public class FooDb {
  @Id
  private String id;
  ...
}

对应的仓库接口：

@Repository
public interface FooRepository extends MongoRepository<FooDb, String> { ... }

迁移文件：

@ChangeUnit(order="001", ...)
public class CreateFooChangelog {
  ...
  @Execution
  public void migration(FooRepository repository) {
     repository.save(...);
  }
}

重构仅修改了类名和集合名，结构保持不变：

@Document("bar")
public class BarDb {
  @Id
  private String id;
  ...
}

@Repository
public interface BarRepository extends MongoRepository<BarDb, String> { ... }

现有的迁移文件因Foo*类已不存在必须修改，我想到的方案是：若存在foo集合则重命名为bar，否则初始化bar集合的默认数据，修改后的迁移文件如下：

@ChangeUnit(order="001", ...)
public class CreateBarChangelog {
  ...
  @Execution
  public void migration(BarRepository repository) {
     // if foo exists, rename it to bar
     // else: repository.save(...);
  }
}

请问该方法是否正确，或有更优解决方案？

你的方案逻辑是可行的，但需要注意细节，同时还有更贴合Mongock设计理念的优化方案：

一、你的方案的注意事项 #

如果要按你的思路实现，需要解决两个核心问题：

1. 直接操作MongoDB原生API：Spring Data Repository绑定了新的BarDb实体，无法直接操作已删除的foo集合，需要注入MongoTemplate或MongoDatabase来执行集合操作：

@Execution
public void migration(BarRepository repository, MongoTemplate mongoTemplate) {
    MongoDatabase db = mongoTemplate.getMongoDbFactory().getMongoDatabase();
    // 检查foo集合是否存在
    if (db.listCollectionNames().into(new ArrayList<>()).contains("foo")) {
        // 重命名集合，dropTarget参数可根据需求设置是否覆盖已存在的bar集合
        db.getCollection("foo").renameCollection("bar", new RenameCollectionOptions().dropTarget(true));
    } else {
        // 初始化默认数据
        repository.save(...);
    }
}

2. 避免重复执行问题：Mongock通过ChangeUnit的id属性标记已执行的迁移，如果替换后的新迁移单元id和原来的不同，Mongock会认为是新迁移并重复执行。要么复用原迁移单元的id，要么手动处理Mongock的变更日志记录。

二、更符合Mongock最佳实践的方案 #

Mongock的核心设计是保留历史迁移脚本，新增迁移脚本处理变更，不建议修改已执行过的迁移脚本（会破坏变更审计的完整性）。推荐步骤：

1. 保留原迁移脚本与历史类：即使FooDb和FooRepository已经不在业务代码中，也不要删除它们——可以把这些类移到专门的migration-legacy包下，让Mongock能加载到历史迁移中用到的类，避免加载失败。
2. 新增专门的集合重命名迁移单元，设置比原迁移更大的order值（比如002）：

@ChangeUnit(id="rename-foo-to-bar", order="002", author="your-name")
public class RenameFooToBarChangelog {

    @Execution
    public void execute(MongoTemplate mongoTemplate) {
        MongoDatabase db = mongoTemplate.getMongoDbFactory().getMongoDatabase();
        if (db.listCollectionNames().into(new ArrayList<>()).contains("foo")) {
            // 重命名集合
            db.getCollection("foo").renameCollection("bar", new RenameCollectionOptions().dropTarget(false));
            // 可选：如果用了Spring Data的类型映射，更新文档中的_class字段
            mongoTemplate.updateMulti(
                Query.query(Criteria.where("_class").is("com.yourpackage.FooDb")),
                Update.update("_class", "com.yourpackage.BarDb"),
                "bar"
            );
        }
    }

    @RollbackExecution
    public void rollback(MongoTemplate mongoTemplate) {
        // 可选：回滚逻辑，恢复集合名与_class字段
        MongoDatabase db = mongoTemplate.getMongoDbFactory().getMongoDatabase();
        if (db.listCollectionNames().into(new ArrayList<>()).contains("bar")) {
            db.getCollection("bar").renameCollection("foo", new RenameCollectionOptions().dropTarget(false));
            mongoTemplate.updateMulti(
                Query.query(Criteria.where("_class").is("com.yourpackage.BarDb")),
                Update.update("_class", "com.yourpackage.FooDb"),
                "foo"
            );
        }
    }
}

3. 拆分初始化逻辑：新实例的bar集合初始化逻辑，可以放在另一个独立的ChangeUnit（比如InitializeBarChangelog，order="003"）中，或者通过ApplicationRunner在应用启动时处理，避免与迁移逻辑耦合。

三、为什么不推荐修改原迁移脚本？ #

• 破坏审计追踪：Mongock的核心价值是记录所有变更历史，修改已执行的脚本会导致历史记录与实际执行内容不一致，后续排查问题时会产生混乱。
• 兼容性风险：如果已有环境执行过原迁移脚本，修改后的脚本在这些环境运行时，会因找不到原Foo*类导致Mongock加载失败。

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