Node.js / 系统课时

统一处理接口错误

统一处理接口错误

接口错误如果分散在每个路由里处理,状态码、响应结构和日志很快会不一致。本节用 Express 5 的错误中间件把 404、业务错误和未预期异常收敛到同一出口,并保留 headersSent 场景的正确处理方式。

学习目标

  • 写出符合 Express 5 约定的四参数错误处理中间件
  • 统一返回 HTTP 状态码、错误代码和客户端可见信息
  • 验证同步异常、异步 Promise 拒绝和 404 的处理路径

错误怎样进入统一出口

Express 5 会捕获同步 throw,也会把 async 路由返回 Promise 的拒绝自动交给错误处理链。回调式 API 的错误仍需显式 next(err)。错误中间件必须保留四个参数 (err, req, res, next),并放在普通路由之后。

Express 请求进入路由、404 与错误中间件的处理链

一个实用约定是:可预期错误携带 status 和稳定的 code;未知错误统一返回 500,详细堆栈只写服务端日志。这样不会把数据库地址、文件路径或内部调用栈泄露给客户端。

写一个可运行的错误处理器

下面示例适用于 Express 5.x。HttpError 表示可预期错误;异步 /api/fail 直接抛错即可进入错误中间件;404 中间件负责把“没有任何路由匹配”转换为统一错误对象。

js
import express from 'express';

class HttpError extends Error {
  constructor(status, code, message) {
    super(message);
    this.status = status;
    this.code = code;
  }
}

const app = express();
app.use(express.json());

app.get('/api/users/:id', async (req, res) => {
  if (req.params.id === '999') {
    throw new HttpError(404, 'USER_NOT_FOUND', '用户不存在');
  }

  res.json({ id: req.params.id, name: 'Ada' });
});

app.get('/api/fail', async () => {
  throw new Error('database unavailable');
});

app.use((req, res, next) => {
  next(new HttpError(404, 'ROUTE_NOT_FOUND', '接口不存在'));
});

app.use((err, req, res, next) => {
  if (res.headersSent) {
    return next(err);
  }

  const status =
    Number.isInteger(err.status) && err.status >= 400 && err.status <= 599
      ? err.status
      : 500;

  if (status >= 500) {
    console.error(err);
  }

  res.status(status).json({
    error: {
      code: err.code ?? 'INTERNAL_ERROR',
      message: status >= 500 ? '服务器内部错误' : err.message,
    },
  });
});

app.listen(3000, () => {
  console.log('server listening on 3000');
});

预期结果:保存为 app.mjs 并在已安装 Express 5 的项目中启动后,进程监听 3000 端口。

text
server listening on 3000

用请求验证状态码与响应体

先访问一个可预期的业务错误。curl -i 会同时显示状态行、响应头和响应体,因此比只看 JSON 更适合核对错误处理是否正确。

bash
curl -i http://localhost:3000/api/users/999

预期输出只列关键部分;日期、长度等标准响应头可能不同,但状态码和 JSON 应保持一致。

text
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"error":{"code":"USER_NOT_FOUND","message":"用户不存在"}}

再访问不存在的路由时,应得到 ROUTE_NOT_FOUND;访问 /api/fail 时应得到 500 和通用文案,同时终端记录真实异常。生产环境不要把 err.stack 或数据库错误原文直接放进响应体。

处理已经开始发送的响应

流式下载、SSE 或大文件响应可能在部分数据已经写出后才发生异常。此时 res.headersSent 为 true,自定义错误处理中间件不能再尝试 res.status(...).json(...),否则容易出现“响应头已发送”错误。

正确做法是立即 return next(err),让 Express 默认错误处理器接管连接。对于普通 JSON API,则尽量在发送响应前完成参数校验、权限检查和关键异步操作,避免半写入后才失败。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

统一处理接口错误

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通