API请求保存文档触发ParallelSaveError：同一文档不可并行多次save

你遇到的ParallelSaveError本质是Mongoose检测到同一个文档实例被多次调用save()且这些操作并行执行。虽然你认为每个请求都会重新获取独立的用户文档实例，但偶发的错误说明存在某种场景导致同一个实例被重复触发保存。

可能的原因 #

• 同一实例的重复保存触发：如果你的代码中（比如User模型的pre-save/post-save钩子、其他关联中间件）存在对同一个res.locals.user实例多次调用save()的逻辑，就会触发该错误。
• 异步流程未正确控制：使用回调式的save时，若前一次保存操作未完成，后续代码意外触发了同实例的再次保存（比如钩子中的异步操作延迟导致），就会出现并行冲突。
• 未持久化关联文档的潜在影响：你创建的Folder实例未执行save()就将其_id推入用户的folders数组，虽然Mongoose允许引用未持久化的ObjectId，但这种操作可能导致文档状态跟踪异常，间接引发并行保存检测。

解决方案 #

方案1：改用async/await控制异步流程，确保保存操作串行执行 #

将回调式的查询和保存改为async/await，明确控制操作顺序，避免并行触发：

首先修改中间件：

const getLocalUser = async (req, res, next) => {
  try {
    const user = await User.findById(res.locals.decodedToken.id)
      .populate("folders")
      .populate("files");
    
    if (!user) {
      return res.status(409).json({
        error: true,
        response: "No local user tied to account id",
        status: "NO_LOCAL_USER",
      });
    }

    res.locals.user = user;
    next();
  } catch (err) {
    return res.status(500).json({ error: true, response: err.message });
  }
};

然后修改路由处理函数：

router.post("/", getLocalUser, async (req, res) => {
  try {
    // 先持久化Folder实例，确保_id在数据库中存在
    const folder = new Folder({ ...req.body, owner_ids: [res.locals.user._id] });
    await folder.save();

    // 修改用户文档并串行保存
    res.locals.user.folders.push(folder._id);
    await res.locals.user.save();

    res.status(200).json({ success: true, folder: folder });
  } catch (err) {
    if (err.name === "ParallelSaveError") {
      res.status(400).json({
        error: true,
        response: "用户文档正在并行修改，请稍后重试",
      });
    } else {
      res.status(500).json({ error: true, response: err.message });
    }
  }
});

方案2：检查并清理User模型中的钩子逻辑 #

查看你的User模型是否存在pre-save或post-save钩子，若钩子中存在对用户文档的save()调用，会导致同一实例被多次保存。例如：

// 错误示例：pre-save钩子中再次调用save
userSchema.pre('save', async function(next) {
  // 某些修改操作
  this.someField = 'value';
  await this.save(); // 这里会触发并行保存错误
  next();
});

如果存在此类逻辑，需重构钩子，避免在钩子中重复调用save()，改为直接修改字段后由主流程触发保存。

方案3：备选：使用原子更新操作（findByIdAndUpdate） #

如果你想彻底避免并行保存问题，可以使用Mongoose的原子更新方法，直接在数据库层面完成数组推送，无需先查询再保存：

router.post("/", async (req, res) => {
  try {
    const folder = new Folder({ ...req.body, owner_ids: [res.locals.decodedToken.id] });
    await folder.save();

    const updatedUser = await User.findByIdAndUpdate(
      res.locals.decodedToken.id,
      { $push: { folders: folder._id } },
      { new: true, populate: ['folders', 'files'] } // 返回更新后的文档并关联字段
    );

    res.locals.user = updatedUser;
    res.status(200).json({ success: true });
  } catch (err) {
    res.status(500).json({ error: true, response: err.message });
  }
});

这种方式虽然多了一次查询，但原子操作能避免并发修改冲突，适合高并发场景。

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