Node/Express：传递res到辅助函数为何触发ERR_HTTP_HEADERS_SENT错误？

问题场景 #

使用Node.js v18.2 + Express v4.18构建Web应用时，尝试将验证逻辑封装为辅助函数并传递res对象直接返回响应，但触发了[ERR_HTTP_HEADERS_SENT]: Cannot set headers after they are sent to the client错误。简化的错误代码示例如下：

// 封装的验证辅助函数
function validateInput(req, res) {
  if (!req.body.amount) {
    res.json({ error: '金额不能为空' });
    return; // 仅跳出辅助函数
  }
  if (typeof req.body.amount !== 'number') {
    res.json({ error: '金额必须是数字' });
    return; // 仅跳出辅助函数
  }
}

// Express路由处理函数
app.post('/transfer', (req, res) => {
  validateInput(req, res);
  // 验证失败时，这里仍会执行，导致重复发送响应
  res.json({ success: true });
});

你已经通过让辅助函数返回布尔值实现了正确逻辑，但有两个疑问需要解答：

疑问A：为何传递res会导致错误？ #

不是不能传递res，而是传递res后，辅助函数中的res.json()仅完成了响应发送，但无法终止外层路由处理函数的执行流程。

• 辅助函数中的return只会跳出当前辅助函数，外层的路由处理函数会继续执行后续代码（比如示例中的res.json({ success: true })）。
• HTTP协议要求一个请求只能对应一个完整的响应，当辅助函数已经通过res.json()发送了响应头和响应体后，后续代码再次调用res.json()会尝试重复设置响应头，触发Node.js的ERR_HTTP_HEADERS_SENT错误。

疑问B：为何res.json({})加return无法阻止后续响应？ #

核心原理： #

1. res.json()的作用：它会设置响应的Content-Type为application/json，写入响应体，并触发响应发送，但不会立即终止当前执行上下文的代码流。
2. return的作用范围：辅助函数中的return仅能终止辅助函数本身的执行，外层路由处理函数的代码依然会继续往下走。只有在路由处理函数内部执行return，才能终止后续代码的运行。

举个例子，即使你在辅助函数里写了return res.json(...)，也只是把res.json()的返回值（res对象）作为辅助函数的返回值，但外层路由处理函数不会因为这个返回值而停止执行。

正确的实现方式 #

方式1：辅助函数返回验证结果，路由函数控制流程 #

让辅助函数返回验证状态和错误信息，在路由处理函数中判断后决定是否发送响应：

function validateInput(req) {
  if (!req.body.amount) {
    return { valid: false, error: '金额不能为空' };
  }
  if (typeof req.body.amount !== 'number') {
    return { valid: false, error: '金额必须是数字' };
  }
  return { valid: true };
}

app.post('/transfer', (req, res) => {
  const validation = validateInput(req);
  if (!validation.valid) {
    return res.json({ error: validation.error }); // 这里的return会终止路由函数
  }
  // 验证通过后执行业务逻辑
  res.json({ success: true });
});

方式2：使用Express中间件（更符合框架设计） #

Express的中间件天然适合处理前置验证逻辑，验证失败时直接返回响应，验证通过则调用next()进入后续处理：

function validateTransfer(req, res, next) {
  if (!req.body.amount) {
    return res.json({ error: '金额不能为空' });
  }
  if (typeof req.body.amount !== 'number') {
    return res.json({ error: '金额必须是数字' });
  }
  next(); // 验证通过，进入下一个处理函数
}

app.post('/transfer', validateTransfer, (req, res) => {
  // 仅在验证通过时执行
  res.json({ success: true });
});

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