菜鸟教程
教程 fastify tutorial

自定义错误处理

Fastify 提供灵活的机制来自定义错误处理流程，包括全局错误钩子、Schema 校验错误格式化、以及手动抛出业务错误等。

全局错误处理钩子

使用 setErrorHandler 方法可以统一处理所有未捕获的错误：

js 
fastify.setErrorHandler((error, request, reply) => {
  request.log.error(error); // 打印日志
  reply.status(error.statusCode || 500).send({
    error: true,
    message: error.message
  });
});

该方法适用于：

  • 请求处理函数中未捕获的异常
  • Schema 校验失败
  • 插件内部抛出的异常

Schema 校验错误格式化

你可以通过 setValidatorCompiler 和 setSchemaErrorFormatter 来自定义校验器和错误格式：

js 
fastify.setSchemaErrorFormatter((errors, dataVar) => {
  return new Error(`校验失败：${errors[0].message}`);
});

默认情况下，Fastify 使用 AJV 生成详细的校验错误信息。

手动抛出 HTTP 错误

Fastify 提供 fastify.httpErrors 工具对象，可快速抛出带状态码的错误：

js 
fastify.get('/auth', async (request, reply) => {
  throw fastify.httpErrors.unauthorized('未登录或 Token 无效');
});

常见方法有：

  • badRequest()
  • unauthorized()
  • forbidden()
  • notFound()
  • internalServerError()

局部错误处理（每个路由）

每个路由也可以设置独立的错误处理函数：

js 
fastify.get('/user', {
  handler: async () => {
    throw new Error('故意抛错');
  },
  errorHandler: (error, request, reply) => {
    reply.status(400).send({ msg: '自定义错误信息' });
  }
});

日志控制

可结合 request.log 输出结构化错误日志，方便排查：

js 
fastify.setErrorHandler((error, request, reply) => {
  request.log.warn({ err: error }, '请求出错');
  reply.status(500).send({ msg: '服务器内部错误' });
});

相关内容