仅调用一次save仍触发Mongoose ParallelSaveError的原因与解决

问题描述 #

使用Mongoose更新文档并调用save()时触发ParallelSaveError，但代码中仅显式执行了一次save操作，功能实际正常却抛出错误。

相关代码 #

更新/保存用户数据的路由 #

update: function(req, res){
    userLogic.updateUser(res.locals.user, req.body)
        .save()
        .then((user)=>{
            return res.redirect("/user/account");
        })
        .catch((err)=>{
            console.error(err);
            req.session.toaster = "error";
            req.session.toastMessage = "ERROR: unable to update user data";
            return res.redirect("/user/account");
        });
},

userLogic.updateUser()函数 #

updateUser: function(user, data){
    if(!data) throw new SyntaxError("arguments");
    if(!user) throw new TypeError("user");
    email = data.email.toLowerCase();
    if(!isValidEmail(email)) throw new SyntaxError("invalid email");

    user.name = data.name;
    user.email = email;
    user.country = data.country;
    user.address = data.address;

    return user;
}

错误成因 #

ParallelSaveError是Mongoose防止同一个文档实例同时发起多个未完成save操作的保护机制。仅显式调用一次save却触发错误，常见原因有：

• 重复请求：前端意外触发两次提交（比如按钮双击），导致同一个用户实例被连续调用save。
• 未完成的异步操作：res.locals.user这个文档实例在当前请求之前，已经有一个未完成的save操作（比如中间件、之前的异步逻辑中调用了save但未等待完成）。
• 实例状态异常：Mongoose文档实例的内部状态出现异常，导致它误判存在并行的save操作。

解决方法 #

方法1：改用直接更新数据库的方法（推荐） #

放弃“获取实例-修改属性-调用save”的流程，改用findByIdAndUpdate或updateOne这类直接操作数据库的方法，绕过内存中的文档实例状态问题：

update: function(req, res){
    const userId = res.locals.user._id;
    const { name, email, country, address } = req.body;
    const lowerEmail = email.toLowerCase();

    // 先校验邮箱格式
    if(!isValidEmail(lowerEmail)) {
        req.session.toaster = "error";
        req.session.toastMessage = "ERROR: invalid email";
        return res.redirect("/user/account");
    }

    User.findByIdAndUpdate(
        userId,
        { name, email: lowerEmail, country, address },
        { new: true, runValidators: true } // 返回更新后的文档，并运行验证器
    )
    .then(() => res.redirect("/user/account"))
    .catch(err => {
        console.error(err);
        req.session.toaster = "error";
        req.session.toastMessage = "ERROR: unable to update user data";
        res.redirect("/user/account");
    });
},

方法2：防止重复提交与实例锁 #

• 前端层面：给提交按钮添加点击后禁用的逻辑，避免用户双击触发重复请求。
• 后端层面：给文档实例添加临时锁标记，确保同一时间只有一个save操作执行：

update: function(req, res){
    const user = res.locals.user;

    // 检查是否已有正在进行的save操作
    if(user._isSaving) {
        req.session.toaster = "error";
        req.session.toastMessage = "ERROR: user data is being updated, please wait";
        return res.redirect("/user/account");
    }

    user._isSaving = true;
    userLogic.updateUser(user, req.body)
        .save()
        .then(updatedUser => {
            updatedUser._isSaving = false;
            res.redirect("/user/account");
        })
        .catch(err => {
            user._isSaving = false;
            console.error(err);
            req.session.toaster = "error";
            req.session.toastMessage = "ERROR: unable to update user data";
            res.redirect("/user/account");
        });
},

方法3：排查异步逻辑与中间件 #

检查项目中是否有中间件、前置钩子（pre('save')）或其他异步逻辑，对res.locals.user实例调用了save但未正确等待Promise完成，导致实例处于待保存状态。

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