异常处理

import app from '@adonisjs/core/services/app'
import { HttpContext, ExceptionHandler } from '@adonisjs/core/http'
import type { StatusPageRange, StatusPageRenderer } from '@adonisjs/core/types/http'

export default class HttpExceptionHandler extends ExceptionHandler {
  /**
   * 控制是否详细显示带有堆栈跟踪的错误。
   * 在生产环境中自动禁用，以保护敏感信息。
   */
  protected debug = !app.inProduction

  /**
   * 为特定状态码启用自定义 HTML 错误页面。
   * 通常在生产环境中启用以提供更好的用户体验。
   */
  protected renderStatusPages = app.inProduction

  /**
   * 将状态码或范围映射到视图模板。
   * 键可以是特定代码如 '404'，或范围如 '500..599'。
   */
  protected statusPages: Record<StatusPageRange, StatusPageRenderer> = {
    '404': (error, { view }) => {
      return view.render('pages/errors/not_found', { error })
    },
    '500..599': (error, { view }) => {
      return view.render('pages/errors/server_error', { error })
    },
  }

  /**
   * 将错误转换为面向客户端的 HTTP 响应。
   * 重写以自定义错误响应格式。
   */
  async handle(error: unknown, ctx: HttpContext) {
    return super.handle(error, ctx)
  }

  /**
   * 记录错误或将它们发送到监控服务。
   * 切勿尝试从此方法发送 HTTP 响应。
   */
  async report(error: unknown, ctx: HttpContext) {
    return super.report(error, ctx)
  }
}

import router from '@adonisjs/core/services/router'
import { Exception } from '@adonisjs/core/exceptions'

router.get('fatal', () => {
  /**
   * 抛出一个带有 500 状态码的异常
   * 以及一个用于识别的自定义错误码
   */
  throw new Exception('Something went wrong', { 
    status: 500, 
    code: 'E_RUNTIME_EXCEPTION' 
  })
})

import { errors as vineJSErrors } from '@vinejs/vine'
import { HttpContext, ExceptionHandler } from '@adonisjs/core/http'

export default class HttpExceptionHandler extends ExceptionHandler {
  protected debug = !app.inProduction
  protected renderStatusPages = app.inProduction

  async handle(error: unknown, ctx: HttpContext) {
    /**
     * 使用 instanceof 检查错误是否为 VineJS 验证错误
     * 以安全地识别错误类型
     */
    if (error instanceof vineJSErrors.E_VALIDATION_ERROR) {
      /**
       * 直接将验证消息作为 JSON 返回
       * 状态码为 422 Unprocessable Entity
       */
      ctx.response.status(422).send(error.messages)
      return
    }

    /**
     * 对于所有其他错误，委托给父类
     * 它处理默认的错误转换逻辑
     */
    return super.handle(error, ctx)
  }
}

import router from '@adonisjs/core/services/router'
import { createPostValidator } from '#validators/post'

router.post('posts', async ({ request }) => {
  /**
   * 如果验证失败，VineJS 会抛出 E_VALIDATION_ERROR
   * 它由我们的自定义处理器捕获并返回
   * 带有 422 状态码的验证消息
   */
  await request.validateUsing(createPostValidator)
})

export default class HttpExceptionHandler extends ExceptionHandler {
  async report(error: unknown, ctx: HttpContext) {
    /**
     * 首先调用父类的 report 方法，以确保
     * 错误使用默认行为被记录
     */
    await super.report(error, ctx)

    /**
     * 在此处添加自定义报告逻辑，例如
     * 发送到 Sentry、Bugsnag 或其他服务
     */
  }
}

export default class HttpExceptionHandler extends ExceptionHandler {
  protected context(ctx: HttpContext) {
    return {
      /**
       * 包含唯一的请求 ID 以在日志中
       * 追踪这个特定请求
       */
      requestId: ctx.request.id(),
      
      /**
       * 如果可用，添加已认证用户的 ID
       * 以识别哪个用户遇到了错误
       */
      userId: ctx.auth.user?.id,
      
      /**
       * 包含 IP 地址用于安全监控
       * 以及识别错误中的模式
       */
      ip: ctx.request.ip(),
    }
  }
}

export default class HttpExceptionHandler extends ExceptionHandler {
  /**
   * 不应报告的 HTTP 状态码。
   * 这些通常是客户端错误，并不表示
   * 你的应用存在问题。
   */
  protected ignoreStatuses = [400, 401, 403, 404, 422]

  /**
   * 不应报告的错误码。
   * 这些是针对预期错误条件的
   * 特定于应用的错误码。
   */
  protected ignoreCodes = ['E_VALIDATION_ERROR', 'E_UNAUTHORIZED_ACCESS']
}

export default class HttpExceptionHandler extends ExceptionHandler {
  async report(error: unknown, ctx: HttpContext) {
    /**
     * 将错误转换为包含状态码和错误码的
     * 标准化 HTTP 错误格式
     */
    const httpError = this.toHttpError(error)
    
    /**
     * 仅当它通过 shouldReport 检查时才报告错误，
     * 该检查会验证它不在 ignoreStatuses 或 ignoreCodes 中
     */
    if (this.shouldReport(httpError)) {
      // 在此处添加你的自定义报告逻辑
      // 例如：发送到外部监控服务
    }
  }
}

node ace make:exception PaymentFailed

CREATE: app/exceptions/payment_failed_exception.ts

import { Exception } from '@adonisjs/core/exceptions'
import { HttpContext } from '@adonisjs/core/http'

export default class PaymentFailedException extends Exception {
  /**
   * 此异常的 HTTP 状态码。
   * 设置为静态属性，以便无需
   * 实例化异常即可访问。
   */
  static status = 400

  /**
   * 通过将异常转换为 HTTP 响应来处理它。
   * 当抛出此异常且未被捕获时，
   * 会自动调用此方法。
   */
  handle(error: this, { response }: HttpContext) {
    return response
      .status(error.constructor.status)
      .send('Unable to process the payment. Please try again')
  }

  /**
   * 报告异常以进行记录和监控。
   * 此方法在 handle() 之前调用，以记录
   * 错误的发生。
   */
  report(error: this, { logger, auth }: HttpContext) {
    logger.error(
      { user: auth.user }, 
      'Payment failed for user %s', 
      auth.user?.id
    )
  }
}