MongoDB迁移框架中LUUID转标准UUID仅Shell生效问题排查

问题背景 #

你编写了一个JavaScript脚本，意图将MongoDB集合中的Legacy UUID（LUUID）替换为标准UUID，在Robo 3T Shell中运行完全正常，但通过C#的EvalAsync方法执行时，却只是把原有LUUID换成了另一个LUUID，没有完成预期的格式转换。

核心原因 #

问题出在MongoDB的UUID()函数的环境依赖行为上：

• Robo 3T（原Studio 3T）的Shell默认采用RFC 4122标准UUID作为UUID()函数的输出格式，所以当你传入v4格式的字符串时，它会生成标准UUID的二进制表示。
• 而C#驱动的Eval操作上下文里，UUID()函数默认生成的是MongoDB Legacy UUID（也就是早期的UUID v1变体格式）。即使你传入了正确的v4字符串，这个函数还是会按Legacy规则处理，最终生成的依然是LUUID，而非标准UUID。

另外需要注意：Eval操作在MongoDB 3.0版本之后已经被官方废弃，这也是不推荐使用它的一个重要原因。

解决方案 #

方案1：修改JavaScript脚本，明确指定标准UUID格式

不要依赖UUID()函数的默认行为，改用MongoDB的BinData()函数直接构造标准UUID（BinData类型4对应RFC 4122标准UUID）。修改后的脚本如下：

function fixIds(collectionName) { 
  function uuidv4() { 
    return 'xxxxxxxxxxxx4xxxyxxxxxxxxxxxxxxx'.replace(/[xy]/g, function (c) { 
      var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8); 
      return v.toString(16); 
    }); 
  } 
  var collection = db.getCollection(collectionName); 
  // 用BinData(4, ...)明确生成标准UUID
  var items = collection.find({}).toArray().map(x => Object.assign(x, { _id: BinData(4, uuidv4()) })); 
  collection.drop(); 
  collection.insertMany(items); 
} 
fixIds("specialoffers");

BinData(4, uuidString)会直接把你的v4字符串转换成标准UUID的二进制存储格式，不管在哪个执行环境下都能得到一致的结果。

方案2：用C#驱动直接处理迁移（推荐）

既然已经用C#开发，完全可以避开Eval这个废弃的API，直接通过驱动完成数据的读取、转换和写入，这样更可控也更符合MongoDB的最佳实践：

public static async Task MigrateLegacyUuidsToStandardAsync(IMongoDatabase database, string collectionName)
{
    var collection = database.GetCollection<BsonDocument>(collectionName);
    // 读取所有文档
    var documents = await collection.Find(_ => true).ToListAsync();
    
    // 替换每个文档的_id为标准UUID
    var updatedDocuments = documents.Select(doc => 
    {
        // 生成标准UUID并指定存储格式
        doc["_id"] = new BsonBinaryData(Guid.NewGuid(), GuidRepresentation.Standard);
        return doc;
    }).ToList();
    
    // 清空原集合并插入新文档
    await collection.DropCollectionAsync();
    await collection.InsertManyAsync(updatedDocuments);
}

这个方法直接用C#的Guid.NewGuid()生成标准UUID，通过GuidRepresentation.Standard指定MongoDB的存储格式，完全避开了Shell函数的行为差异问题。

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