Express.js 错误处理中间件：轻松应对那些“不听话”的代码

引言

大家好，欢迎来到今天的讲座！今天我们要聊的是一个非常重要的话题——如何在 Express.js 应用程序中实现错误处理中间件。如果你曾经写过任何 Node.js 代码，尤其是使用 Express.js 框架的项目，你一定遇到过那些“不听话”的代码。它们时不时地抛出一些奇怪的错误，让你抓耳挠腮，甚至怀疑人生。别担心，我们今天就来一起探讨如何优雅地处理这些错误，让我们的应用程序更加健壮和可靠。

为什么需要错误处理？

在编写任何应用程序时，错误是不可避免的。无论是用户输入了无效的数据，还是服务器出现了内部故障，错误都会发生。如果我们不妥善处理这些错误，用户可能会看到一些令人困惑的错误页面，甚至导致整个应用程序崩溃。因此，错误处理不仅仅是开发中的一个“可选项”，而是必须认真对待的关键部分。

Express.js 提供了一个非常灵活的中间件机制，可以让我们轻松地捕获和处理各种类型的错误。通过合理的错误处理，我们可以确保应用程序在遇到问题时能够优雅地恢复，而不是直接挂掉。更重要的是，良好的错误处理可以提升用户体验，让用户感到更加安心。

本文结构

在这篇文章中，我们将逐步探讨如何在 Express.js 中实现错误处理中间件。我们会从最基础的概念开始，逐步深入到更复杂的场景。文章的主要内容包括：

什么是中间件？
Express.js 中的错误处理机制
如何编写自定义错误处理中间件
常见的错误类型及处理方法
结合第三方库进行更强大的错误处理
最佳实践与注意事项

好了，闲话少说，让我们开始吧！😊

1. 什么是中间件？

在深入讨论错误处理之前，我们先来了解一下什么是中间件（Middleware）。中间件是 Express.js 中非常重要的一部分，它就像一个“过滤器”，可以在请求到达最终的目标路由之前对其进行处理。你可以把中间件想象成一个流水线上的工人，每个工人负责完成特定的任务，然后再把任务传递给下一个工人。

中间件的工作原理

在 Express.js 中，中间件是一个函数，它接收三个参数：req、res 和 next。req 是请求对象，包含了所有来自客户端的请求信息；res 是响应对象，用于向客户端发送响应；next 是一个函数，调用它可以让控制权传递给下一个中间件或路由处理器。

app.use((req, res, next) => {
  console.log('这是第一个中间件');
  next(); // 调用 next() 将控制权传递给下一个中间件
});

在这个例子中，当请求到达时，Express 会依次调用所有的中间件。每个中间件都可以对请求进行处理，或者直接结束请求并返回响应。如果中间件调用了 next()，则表示它已经完成了自己的工作，控制权将传递给下一个中间件或路由处理器。

中间件的种类

Express.js 支持多种类型的中间件，主要包括以下几类：

应用级中间件：全局应用于整个应用程序，适用于所有请求。
路由级中间件：仅应用于特定的路由或路由组。
错误处理中间件：专门用于捕获和处理错误。
内置中间件：如 express.static，用于处理静态文件。
第三方中间件：如 body-parser，用于解析请求体。

今天我们主要关注的是错误处理中间件，它可以帮助我们捕获并处理应用程序中的各种错误。

2. Express.js 中的错误处理机制

在 Express.js 中，错误处理中间件是一种特殊的中间件，它用于捕获和处理应用程序中的错误。与普通中间件不同，错误处理中间件有四个参数：err、req、res 和 next。其中，err 是一个错误对象，包含了错误的详细信息。

错误处理中间件的基本结构

一个简单的错误处理中间件看起来像这样：

app.use((err, req, res, next) => {
  console.error(err.stack); // 打印错误堆栈
  res.status(500).send('服务器内部错误'); // 返回 500 状态码和错误消息
});

在这个例子中，当应用程序中发生任何错误时，Express 会自动将错误传递给这个中间件。我们可以在这里对错误进行处理，比如记录日志、返回友好的错误页面等。

如何触发错误处理中间件？

要触发错误处理中间件，通常有两种方式：

显式调用 next(err)：在中间件或路由处理器中，如果发生了错误，我们可以调用 next(err)，并将错误对象传递给下一个中间件。Express 会自动将控制权传递给错误处理中间件。
```
app.get('/error', (req, res, next) => {
 const err = new Error('这是一个故意制造的错误');
 next(err); // 触发错误处理中间件
});
```
抛出异常：在中间件或路由处理器中，如果抛出了未捕获的异常，Express 也会自动将其传递给错误处理中间件。
```
app.get('/throw-error', (req, res) => {
 throw new Error('这是一个未捕获的异常');
});
```

这两种方式都会触发错误处理中间件，区别在于显式调用 next(err) 可以让我们更好地控制错误的传递，而抛出异常则更适合处理意外情况。

错误处理的优先级

需要注意的是，错误处理中间件的优先级较低，它只会捕获那些没有被其他中间件或路由处理器处理的错误。因此，我们应该尽量在应用程序的最后注册错误处理中间件，以确保它能够捕获所有的错误。

// 先定义普通路由
app.get('/', (req, res) => {
  res.send('Hello World!');
});

// 再定义错误处理中间件
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).send('服务器内部错误');
});

3. 如何编写自定义错误处理中间件

虽然 Express.js 提供了一些内置的错误处理机制，但很多时候我们需要根据具体的应用需求编写自定义的错误处理中间件。接下来，我们将介绍如何编写一个功能更强大的错误处理中间件，能够处理不同类型的错误，并返回适当的响应。

3.1. 区分不同的错误类型

在实际应用中，错误的类型可能有很多种，比如用户输入错误、数据库查询失败、网络连接超时等。为了提供更好的用户体验，我们应该根据不同的错误类型返回不同的响应。为此，我们可以在错误对象中添加一些自定义属性，帮助我们区分不同的错误类型。

例如，我们可以定义一个自定义的错误类 ApiError，并在其中添加 status 和 message 属性：

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

然后，在路由处理器中，我们可以使用这个自定义的错误类来抛出不同类型的错误：

app.get('/user/:id', (req, res, next) => {
  const userId = parseInt(req.params.id);

  if (isNaN(userId)) {
    return next(new ApiError(400, '无效的用户 ID'));
  }

  // 模拟数据库查询
  const user = users.find(u => u.id === userId);

  if (!user) {
    return next(new ApiError(404, '用户不存在'));
  }

  res.json(user);
});

3.2. 处理不同类型的错误

现在我们有了自定义的错误类，接下来可以在错误处理中间件中根据 status 属性返回不同的响应：

app.use((err, req, res, next) => {
  if (err instanceof ApiError) {
    // 如果是自定义的 API 错误，返回相应的状态码和消息
    res.status(err.status).json({ error: err.message });
  } else {
    // 对于其他类型的错误，返回 500 状态码和默认消息
    console.error(err.stack);
    res.status(500).json({ error: '服务器内部错误' });
  }
});

这样，当用户访问 /user/abc 时，他们会收到 400 状态码和“无效的用户 ID”的错误消息；而当用户访问 /user/999 时，他们会收到 404 状态码和“用户不存在”的错误消息。对于其他未捕获的错误，我们会返回 500 状态码和默认的错误消息。

3.3. 记录错误日志

除了返回适当的响应外，记录错误日志也是非常重要的。通过记录错误日志，我们可以方便地追踪和调试问题。我们可以在错误处理中间件中使用 console.error 来打印错误堆栈，但这只是一个简单的解决方案。在生产环境中，我们通常会使用更专业的日志库，比如 winston 或 pino。

这里我们简单演示一下如何使用 console.error 记录错误日志：

app.use((err, req, res, next) => {
  console.error(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
  console.error(err.stack);

  if (err instanceof ApiError) {
    res.status(err.status).json({ error: err.message });
  } else {
    res.status(500).json({ error: '服务器内部错误' });
  }
});

这段代码会在每次发生错误时打印出请求的时间、方法、URL 以及错误堆栈，方便我们进行调试。

3.4. 返回友好的错误页面

对于前端用户来说，直接返回 JSON 格式的错误信息可能不太友好。我们可以通过检查请求的 Accept 头来判断用户是否希望接收 HTML 页面，如果是的话，我们可以返回一个友好的错误页面。

app.use((err, req, res, next) => {
  console.error(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
  console.error(err.stack);

  if (req.accepts('html')) {
    // 如果用户希望接收 HTML 页面，返回友好的错误页面
    res.status(err.status || 500);
    res.render('error', { message: err.message || '服务器内部错误' });
  } else {
    // 否则返回 JSON 格式的错误信息
    res.status(err.status || 500).json({ error: err.message || '服务器内部错误' });
  }
});

在这个例子中，我们使用了 req.accepts('html') 来判断用户是否希望接收 HTML 页面。如果是的话，我们使用 res.render 渲染一个名为 error 的模板，并传递错误信息给模板。否则，我们仍然返回 JSON 格式的错误信息。

4. 常见的错误类型及处理方法

在实际开发中，我们可能会遇到各种各样的错误类型。为了更好地处理这些错误，我们需要了解它们的特点，并采取相应的措施。接下来，我们将介绍几种常见的错误类型及其处理方法。

4.1. 用户输入错误

用户输入错误是最常见的一类错误，通常是由于用户提交了无效的数据导致的。例如，用户可能输入了不符合格式的电子邮件地址，或者选择了不存在的用户 ID。对于这类错误，我们应该尽早捕获，并返回清晰的错误提示。

app.post('/register', (req, res, next) => {
  const { email, password } = req.body;

  if (!email || !password) {
    return next(new ApiError(400, '缺少必填字段'));
  }

  if (!validateEmail(email)) {
    return next(new ApiError(400, '无效的电子邮件地址'));
  }

  // 继续处理注册逻辑...
});

在这个例子中，我们在接收到用户输入后立即进行了验证。如果发现任何问题，我们会立即返回 400 状态码和相应的错误消息，避免不必要的后续处理。

4.2. 数据库查询错误

数据库查询错误是另一种常见的错误类型，可能是由于数据库连接失败、查询语句错误或数据不存在等原因引起的。对于这类错误，我们应该尽量提供有意义的错误信息，而不是直接返回通用的 500 状态码。

app.get('/users', async (req, res, next) => {
  try {
    const users = await db.query('SELECT * FROM users');
    res.json(users);
  } catch (err) {
    next(new ApiError(500, '数据库查询失败'));
  }
});

在这个例子中，我们使用了 try...catch 语句来捕获数据库查询中的错误。如果发生错误，我们会返回 500 状态码和“数据库查询失败”的错误消息。当然，你也可以根据具体的错误类型返回更详细的错误信息。

4.3. 第三方服务调用错误

在现代 Web 应用中，我们经常需要调用第三方服务，比如支付网关、短信服务或社交媒体 API。然而，这些服务可能会因为网络问题、API 限制或其他原因而无法正常工作。对于这类错误，我们应该提供适当的错误处理机制，避免影响整个应用程序的正常运行。

const axios = require('axios');

app.get('/weather', async (req, res, next) => {
  try {
    const response = await axios.get('https://api.weather.com/v1/weather');
    res.json(response.data);
  } catch (err) {
    if (err.response && err.response.status === 404) {
      return next(new ApiError(404, '天气数据不可用'));
    }
    next(new ApiError(500, '第三方服务调用失败'));
  }
});

在这个例子中，我们使用了 axios 库来调用第三方天气 API。如果 API 返回 404 状态码，我们会返回“天气数据不可用”的错误消息；对于其他类型的错误，我们会返回“第三方服务调用失败”的错误消息。

4.4. 身份验证错误

身份验证错误是另一个常见的错误类型，通常发生在用户尝试访问受保护的资源时。对于这类错误，我们应该返回适当的 HTTP 状态码，并提供清晰的错误提示。

const jwt = require('jsonwebtoken');

app.get('/protected', (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];

  if (!token) {
    return next(new ApiError(401, '未提供有效的授权令牌'));
  }

  try {
    const decoded = jwt.verify(token, 'secret-key');
    res.json({ message: '欢迎访问受保护的资源' });
  } catch (err) {
    return next(new ApiError(403, '无效的授权令牌'));
  }
});

在这个例子中，我们首先检查请求头中是否包含有效的授权令牌。如果没有，我们会返回 401 状态码和“未提供有效的授权令牌”的错误消息。如果令牌无效，我们会返回 403 状态码和“无效的授权令牌”的错误消息。

5. 结合第三方库进行更强大的错误处理

虽然 Express.js 自带的错误处理机制已经足够强大，但在某些情况下，我们可能需要更高级的功能，比如分布式日志、性能监控或自动重试机制。为了实现这些功能，我们可以结合一些第三方库来进行更强大的错误处理。

5.1. 使用 Winston 进行日志记录

Winston 是一个非常流行的日志库，支持多种日志传输方式（如文件、控制台、MongoDB 等），并且可以根据不同的日志级别（如 info、warn、error）进行分类记录。

首先，我们需要安装 Winston：

npm install winston

然后，我们可以在应用程序中配置 Winston 日志记录器：

const winston = require('winston');

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

app.use((err, req, res, next) => {
  logger.error(err.message, { stack: err.stack });

  if (err instanceof ApiError) {
    res.status(err.status).json({ error: err.message });
  } else {
    res.status(500).json({ error: '服务器内部错误' });
  }
});

在这个例子中，我们创建了一个 Winston 日志记录器，并配置了两个日志传输器：一个是控制台传输器，用于实时输出日志；另一个是文件传输器，用于将错误日志保存到 error.log 文件中。我们还在 error.log 文件中只记录错误级别的日志，而在 combined.log 文件中记录所有级别的日志。

5.2. 使用 Morgan 进行请求日志记录

Morgan 是一个轻量级的 HTTP 请求日志库，可以帮助我们记录每个请求的详细信息，如请求方法、URL、响应时间等。这对于调试和性能优化非常有帮助。

首先，我们需要安装 Morgan：

npm install morgan

然后，我们可以在应用程序中使用 Morgan 记录请求日志：

const morgan = require('morgan');

app.use(morgan('combined'));

app.get('/', (req, res) => {
  res.send('Hello World!');
});

在这个例子中，我们使用了 morgan('combined') 来记录标准的 Combined 日志格式。你可以根据需要选择其他格式，如 common、short 或 tiny。

5.3. 使用 Sentry 进行错误监控

Sentry 是一个流行的错误监控平台，可以帮助我们实时跟踪和分析应用程序中的错误。它不仅可以捕获未捕获的异常，还可以记录错误的上下文信息（如用户 ID、浏览器版本等），并提供详细的错误报告。

首先，我们需要安装 Sentry SDK：

npm install @sentry/node

然后，我们可以在应用程序中初始化 Sentry 并捕获错误：

const Sentry = require('@sentry/node');

Sentry.init({
  dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0'
});

app.use(Sentry.Handlers.requestHandler());

app.get('/error', (req, res, next) => {
  const err = new Error('这是一个故意制造的错误');
  Sentry.captureException(err);
  next(err);
});

app.use(Sentry.Handlers.errorHandler());

app.use((err, req, res, next) => {
  res.status(500).json({ error: '服务器内部错误' });
});

在这个例子中，我们使用了 Sentry.init 初始化 Sentry SDK，并使用 Sentry.Handlers.requestHandler 和 Sentry.Handlers.errorHandler 来捕获请求和错误。我们还使用了 Sentry.captureException 手动捕获了一个错误，并将其发送到 Sentry 服务器。

6. 最佳实践与注意事项

在实现错误处理中间件时，有一些最佳实践和注意事项可以帮助我们编写更健壮、更可靠的代码。下面是一些建议：

6.1. 尽早捕获和处理错误

尽可能在早期捕获和处理错误，避免让错误传播到后续的中间件或路由处理器。这不仅可以提高应用程序的性能，还可以减少不必要的计算和资源消耗。

6.2. 避免泄露敏感信息

在返回错误信息时，应该避免泄露敏感信息，如数据库密码、API 密钥等。对于生产环境，最好只返回简短的错误提示，而不暴露具体的错误堆栈或技术细节。

6.3. 使用统一的错误处理机制

在整个应用程序中使用统一的错误处理机制，可以简化代码维护，并确保所有错误都得到一致的处理。你可以通过定义一个全局的错误处理中间件来实现这一点。

6.4. 记录详细的日志

记录详细的错误日志对于调试和问题排查非常重要。你应该尽可能多地记录错误的上下文信息，如请求 URL、用户 ID、设备信息等。这样可以帮助你更快地定位问题，并找到解决方案。

6.5. 定期清理日志文件

随着时间的推移，日志文件可能会变得非常庞大，占用大量的磁盘空间。你应该定期清理日志文件，或者使用日志轮转工具（如 logrotate）来自动管理日志文件的大小和数量。

6.6. 测试错误处理逻辑

不要忘记为错误处理逻辑编写测试用例。通过模拟各种错误场景，你可以确保错误处理中间件能够正确地捕获和处理错误，避免潜在的问题。

总结

今天我们一起探讨了如何在 Express.js 中实现错误处理中间件。我们从中间件的基本概念入手，逐步深入到错误处理的具体实现。通过编写自定义的错误处理中间件，我们可以更好地捕获和处理各种类型的错误，并提供友好的错误页面和日志记录。此外，结合第三方库（如 Winston、Morgan 和 Sentry），我们还可以实现更强大的错误监控和日志管理功能。

希望这篇文章能帮助你更好地理解和掌握 Express.js 中的错误处理机制。如果你有任何问题或建议，欢迎在评论区留言！😊

感谢大家的聆听，祝你们编码愉快！✨