Mongoose 展开运算符的隐藏陷阱：内部属性污染问题

前言

在使用 Mongoose 开发 Node.js 应用时，我们经常会用到 JavaScript 的展开运算符（spread operator）来合并对象。然而，当你对 Mongoose 文档使用展开运算符时，可能会遇到一个隐蔽的问题：Mongoose 的内部属性会意外地被复制到新对象中。

问题重现

让我们通过一个简单的例子来看看这个问题：

// 定义一个简单的 Schema
const UserSchema = new mongoose.Schema({
  name: String,
  email: String,
  posts: [{
    title: String,
    content: String
  }]
});

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

// 从数据库查询用户
const user = await User.findById(userId);

// 获取第一篇文章（这是一个 Mongoose 子文档）
const firstPost = user.posts[0];

// 场景 1：直接序列化 - 看起来正常
console.log(JSON.stringify(firstPost));
// 输出: {"title":"Hello World","content":"My first post"}

// 场景 2：使用展开运算符后再序列化 - 出现奇怪的属性
const updatedPost = {
    ...firstPost,  // ⚠️ 问题出现在这里
    title: 'Updated Title'
};

console.log(JSON.stringify(updatedPost));
// 输出: {
//   "__parentArray": [...],
//   "$__parent": {...},
//   "$__": {...},
//   "_doc": {...},
//   "title": "Updated Title",
//   "content": "My first post"
// }

你会惊讶地发现：同样是序列化，为什么第一次看不到内部属性，第二次却出现了？

原因分析

Mongoose 子文档的内部结构

当你在 Schema 中定义数组字段时，数组中的每个元素都是 Mongoose 子文档（Subdocument）：

posts: [{
  title: String,
  content: String
}]

Mongoose 会为每个子文档添加内部属性来跟踪它与父文档的关系：

• __parentArray: 指向包含该子文档的父数组
• $__parent: 指向父文档
• $__: Mongoose 内部状态对象
• _doc: 实际的文档数据

为什么直接序列化看不到，展开后就看到了？

这是因为 JSON.stringify() 的执行机制：

场景 1：直接序列化 Mongoose 对象

JSON.stringify(firstPost)

当序列化一个对象时，JSON.stringify() 会先检查对象是否有 toJSON() 方法。Mongoose 文档和子文档都实现了 toJSON() 方法，该方法会：

1. 自动过滤掉所有内部属性（以 $ 或 _ 开头的）
2. 只返回实际的业务数据
3. 因此输出看起来很干净

场景 2：序列化展开后的对象

const updatedPost = { ...firstPost, title: 'Updated' };
JSON.stringify(updatedPost)

关键在于：

1. 展开运算符 ... 会复制对象的所有可枚举属性，包括那些内部属性
2. 新创建的 updatedPost 是一个普通 JavaScript 对象（POJO）
3. 普通对象没有 Mongoose 的 toJSON() 方法
4. 因此 JSON.stringify() 会序列化所有属性，内部属性就暴露出来了

解决方案

方案 1：使用 toObject() 方法（推荐）

在使用展开运算符之前，先将 Mongoose 文档转换为纯 JavaScript 对象：

// ❌ 错误做法
const updatedPost = {
    ...firstPost,  // firstPost 是 Mongoose 子文档
    title: 'Updated Title'
};

// ✅ 正确做法
const updatedPost = {
    ...firstPost.toObject(),  // 转换为纯对象
    title: 'Updated Title'
};

console.log(JSON.stringify(updatedPost));
// 输出: {"title":"Updated Title","content":"My first post"}  // 干净！

适用场景：局部修复，在需要使用展开运算符的地方进行转换。

优点：

• 精确控制，只在需要的地方转换
• 不影响其他使用 Mongoose 方法的代码

缺点：

• 需要记得在每个使用展开运算符的地方都调用 toObject()

方案 2：查询时使用 lean()（推荐用于只读场景）

如果你的查询只是为了读取数据，不需要使用 Mongoose 的文档方法（如 save()），可以在查询时就返回纯对象：

// ❌ 返回 Mongoose 文档
const user = await User.findById(userId);

// ✅ 返回纯 JavaScript 对象
const user = await User.findById(userId).lean();

// 现在可以安全地使用展开运算符
const firstPost = user.posts[0];
const updatedPost = { ...firstPost, title: 'Updated' };  // 没问题！

适用场景：只读操作，不需要调用 save() 等 Mongoose 方法。

优点：

• 一劳永逸，返回的就是纯对象
• 性能更好（不需要实例化 Mongoose 文档）
• 内存占用更少

缺点：

• 无法使用 Mongoose 文档方法（save()、validate() 等）
• 无法使用虚拟属性（virtuals）

方案 3：使用 toJSON()

如果你主要是为了序列化，可以使用 toJSON()：

const plainPost = firstPost.toJSON();
const updatedPost = { ...plainPost, title: 'Updated' };

区别：

• toObject()：返回的对象更完整，包含所有字段
• toJSON()：返回适合序列化的对象，会应用 Schema 的 toJSON 配置

最佳实践

1. 只读查询使用 lean()

// API 返回数据给前端，不需要修改
app.get('/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id).lean();
  res.json(user);  // 安全，没有内部属性
});

2. 需要修改和保存的场景

// 需要调用 save() 方法
const user = await User.findById(userId);
user.name = 'New Name';
await user.save();  // 使用 Mongoose 的保存逻辑

3. 对象合并前先转换

// 合并用户数据和请求数据
const user = await User.findById(userId);
const updatedUser = {
  ...user.toObject(),  // 先转换
  ...req.body
};

4. 处理嵌套数组

const user = await User.findById(userId);

// ❌ 错误：直接 map 子文档
const titles = user.posts.map(post => ({ ...post, viewed: true }));

// ✅ 正确：先转换
const titles = user.posts.map(post => ({ 
  ...post.toObject(), 
  viewed: true 
}));

调试技巧

如果你想查看对象的真实结构（包括所有内部属性），可以使用 console.dir()：

console.dir(firstPost, { depth: null });
// 会显示所有属性，包括 __parentArray 等

性能对比

// 性能测试（10000 次查询）
// Mongoose 文档: ~1200ms
const users1 = await User.find({});

// lean() 查询: ~400ms（快 3 倍）
const users2 = await User.find({}).lean();

结论：如果是只读查询，lean() 不仅避免了内部属性问题，还能显著提升性能。

总结

• Mongoose 子文档携带内部属性用于跟踪状态
• 展开运算符会复制这些内部属性到新对象
• JSON.stringify() 对 Mongoose 对象和普通对象的处理不同
• 解决方案：使用 toObject()、lean() 或 toJSON()
• 最佳实践：根据场景选择合适的方法

记住这个原则：当你要把 Mongoose 文档当成普通对象使用时（如展开、合并），先转换成纯对象。

参考资料

• Mongoose Documents vs POJOs
• Mongoose lean() Tutorial
• Mongoose toJSON() Documentation

---

希望这篇文章能帮你避开 Mongoose 的这个隐藏陷阱！ 👍