Node.js服务层更新文档失败：抛异常还是返回状态？

我是Node.js新手，正在基于Node.js、Express、Mongoose开发应用的服务层类，现在实现updateDocument方法时，纠结于处理文档更新失败（比如传入错误ID）场景的最佳实践。目前有两种实现版本：

版本1：更新失败时返回含success:false的对象 #

async updateDocument(id, updates) { 
  const output = await this.DocumentModel.updateOne({ _id: id }, updates); 
  let message = 'Something went wrong'; 
  let success = false; 
  let updatedItem = null; 
  if (output.nModified) { 
    message = 'Successfully updated document.'; 
    success = true; 
    updatedItem = await this.getDocument(id); 
  } 
  return { message, success, updatedItem}; 
}

版本2：更新失败时抛出错误 #

async updateDocument(id, updates) { 
  const output = await this.DocumentModel.updateOne({ _id: id }, updates); 
  let updatedItem; 
  if (output.nModified) { 
    updatedItem = await this.getDocument(id); 
  } else{ 
    throw new Error("The document wasn't updated") 
  } 
  return updatedItem; 
}

想请教：遇到传入错误ID这类输入问题时，是否应始终抛异常，还是可以返回更新成功与否的状态？两种方案各自的问题是什么？

这是个非常典型的Node.js异步代码风格选择问题，两种方案没有绝对的对错，核心要看你的应用整体的错误处理策略和代码风格一致性，下面帮你拆解两种方案的优劣势和适用场景：

一、返回状态对象（版本1）的优缺点 #

• 优点：
  • 调用方无需额外处理try/catch，代码写法更“扁平”，尤其是在Express路由里，不用嵌套多层try/catch
  • 可以返回更丰富的上下文信息（比如自定义消息、是否成功、更新后的文档），调用方能直接根据返回值做分支处理
• 缺点：
  • 容易被忽略错误：如果调用方忘记检查success字段，可能会把null的updatedItem当成有效数据继续处理，埋下隐性bug
  • 不符合Node.js/JavaScript的“错误优先”或“异常抛出”的通用约定（比如很多内置API、第三方库都是用抛出异常处理不存在的资源）

二、抛出异常（版本2）的优缺点 #

• 优点：
  • 强制调用方处理错误：必须用try/catch或者.catch()捕获异常，避免忽略更新失败的情况
  • 更符合异步代码的“失败即异常”逻辑：传入错误ID导致找不到文档更新，本质是预期外的输入错误，属于异常场景，抛出异常能清晰区分“正常成功”和“异常失败”的分支
  • 代码更简洁：成功路径直接返回结果，失败路径抛出异常，逻辑更清晰
• 缺点：
  • 调用方需要额外编写try/catch代码，在复杂的业务流程中可能会增加嵌套层级
  • 默认的Error对象携带的信息有限，可能需要自定义错误类（比如DocumentNotFoundError）来区分不同类型的异常，方便上层处理

三、最佳实践建议 #

1. 如果你的应用整体采用“异常优先”的错误处理策略（比如Express中用全局错误中间件捕获异常），那优先选择版本2，但建议优化一下：

   • 自定义错误类，区分“文档不存在”和“更新操作失败”（比如数据库连接错误）两种场景
   • 示例优化：

     class DocumentNotFoundError extends Error {
       constructor(message) {
         super(message || "The document wasn't found or updated");
         this.name = "DocumentNotFoundError";
         this.statusCode = 404;
       }
     }
     
     async updateDocument(id, updates) { 
       // 先检查文档是否存在，区分ID错误和无变更的情况
       const exists = await this.DocumentModel.exists({ _id: id });
       if (!exists) {
         throw new DocumentNotFoundError("Document with provided ID does not exist");
       }
       
       const output = await this.DocumentModel.updateOne({ _id: id }, updates); 
       if (!output.nModified) {
         throw new Error("No changes were made to the document");
       }
       return await this.getDocument(id); 
     }
     

   这样上层的Express路由可以用全局错误中间件统一捕获DocumentNotFoundError，返回404响应，其他错误返回500，更规范。

2. 如果你的应用更倾向于“状态返回”的风格，那可以用版本1，但必须强制调用方检查success字段，同时建议明确区分“文档不存在”和“更新无变更”的情况，不要统一返回模糊的错误消息：

   async updateDocument(id, updates) { 
     const exists = await this.DocumentModel.exists({ _id: id });
     if (!exists) {
       return {
         message: 'Document with provided ID does not exist',
         success: false,
         updatedItem: null,
         errorType: 'NOT_FOUND'
       };
     }
     const output = await this.DocumentModel.updateOne({ _id: id }, updates); 
     if (output.nModified) { 
       return {
         message: 'Successfully updated document.',
         success: true,
         updatedItem: await this.getDocument(id),
         errorType: null
       };
     } else {
       return {
         message: 'No changes were made to the document',
         success: false,
         updatedItem: await this.getDocument(id),
         errorType: 'NO_CHANGES'
       };
     }
   }
   

   这样调用方可以根据errorType做更精准的处理，而不是依赖模糊的文本消息。

3. 额外提醒：updateOne的nModified为0有两种情况：一是文档不存在，二是更新的内容和原文档完全一致。如果需要区分这两种场景，建议先调用exists检查文档是否存在，再执行更新，这样能给调用方更准确的反馈。

内容的提问来源于stack exchange，提问作者Dashiell Rose Bark-Huss