全局错误处理

在 Koa 应用中，全局错误处理是保证应用稳定性和提升用户体验的关键部分。通过有效的错误处理机制，可以捕获和处理请求过程中的各种错误，防止应用崩溃，并提供详细的错误信息或友好的错误提示。

错误处理中间件

Koa 提供了一个非常简洁的方式来进行全局错误处理：通过创建一个中间件来捕获和处理所有的错误。以下是一个简单的示例，展示了如何实现全局错误处理中间件。

示例：全局错误处理中间件

// app.js
const Koa = require('koa');
const app = new Koa();

// 错误处理中间件
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    // 捕获错误
    ctx.status = err.status || 500;
    ctx.body = {
      message: err.message,
      stack: process.env.NODE_ENV === 'development' ? err.stack : ''
    };

    // 打印错误信息
    console.error('Error occurred:', err);
  }
});

// 示例路由
app.use(async ctx => {
  if (ctx.path === '/error') {
    throw new Error('Something went wrong!');
  }
  ctx.body = 'Hello, World!';
});

// 启动服务
app.listen(3000, () => {
  console.log('Koa server is running on port 3000');
});

在上面的例子中，app.use 中的错误处理中间件通过 try...catch 捕获请求过程中发生的错误，并设置相应的 HTTP 状态码和错误消息。

• 如果 NODE_ENV 是 development，将输出详细的堆栈信息，有助于调试；
• 如果是生产环境，则只返回简洁的错误消息。

错误处理中间件的工作原理

• 在请求处理的过程中，错误可能发生在任何地方（如数据库操作、API 调用等）。
• 通过在中间件中使用 try...catch，我们可以捕获这些错误，避免应用崩溃。
• 错误被捕获后，Koa 会根据错误的类型和状态码返回适当的 HTTP 响应。

自定义错误类型

有时候，除了捕获常规错误外，可能需要定义特定类型的错误。例如，某些错误可能是由于无效输入导致的，或者是由于请求的数据不存在。我们可以通过自定义错误类型来更清晰地描述错误。

示例：自定义错误类型

class NotFoundError extends Error {
  constructor(message) {
    super(message);
    this.status = 404;
    this.name = 'NotFoundError';
  }
}

class ValidationError extends Error {
  constructor(message) {
    super(message);
    this.status = 400;
    this.name = 'ValidationError';
  }
}

// 错误处理中间件
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    if (err instanceof NotFoundError) {
      ctx.status = err.status;
      ctx.body = { message: err.message };
    } else if (err instanceof ValidationError) {
      ctx.status = err.status;
      ctx.body = { message: err.message };
    } else {
      ctx.status = err.status || 500;
      ctx.body = { message: 'Internal Server Error' };
    }
    console.error('Error occurred:', err);
  }
});

在此例中，我们定义了 NotFoundError 和 ValidationError 两个自定义错误类型。这样，错误处理中间件可以根据错误类型进行有针对性的处理。

错误日志记录

除了将错误信息返回给客户端，通常还需要将错误信息记录到日志中，以便后续排查。可以使用像 winston、log4js 等日志库来实现错误日志的记录。

示例：使用 winston 记录错误日志

npm install winston

const winston = require('winston');

// 创建一个日志记录器
const logger = winston.createLogger({
  level: 'error',
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
  ],
});

// 错误处理中间件
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    // 记录错误日志
    logger.error(`${err.name}: ${err.message}\n${err.stack}`);

    ctx.status = err.status || 500;
    ctx.body = { message: 'Internal Server Error' };
  }
});

通过使用 winston，我们将错误信息记录到 error.log 文件中，这对于生产环境中的问题排查非常有帮助。

错误处理的最佳实践

1. 统一处理：使用全局错误处理中间件来统一处理所有错误，而不是在每个路由或处理函数中手动捕获错误。
2. 详细的错误信息：在开发环境中返回详细的堆栈信息，以便开发人员调试；在生产环境中，返回简洁的错误信息，防止泄漏敏感信息。
3. 自定义错误类型：根据不同的错误情况自定义错误类型，使得错误处理更加清晰和结构化。
4. 错误日志记录：将错误信息记录到日志文件中，以便日后查看和排查问题。

通过实现全局错误处理机制，可以让 Koa 应用更加健壮，提高应用的稳定性和可维护性。