异常参考

在本指南中，我们将梳理框架核心和官方包抛出的已知异常列表。其中一些异常被标记为自处理（self-handled）。自处理异常能够自行转换为 HTTP 响应。

E_ROUTE_NOT_FOUND

当 HTTP 服务器收到针对不存在路由的请求时，会抛出此异常。默认情况下，客户端会收到 404 响应，此外你还可以使用状态页渲染一个 HTML 页面。

状态码：404
自处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_ROUTE_NOT_FOUND) {
  // 处理错误
}

E_ROW_NOT_FOUND

当查找单项的数据库查询失败（例如使用 Model.findOrFail()）时，会抛出此异常。默认情况下，客户端会收到 404 响应，此外你还可以使用状态页渲染一个 HTML 页面。

状态码：404
自处理：否

import { errors as lucidErrors } from '@adonisjs/lucid'
if (error instanceof lucidErrors.E_ROW_NOT_FOUND) {
  // 处理错误
  console.log(`${error.model?.name || 'Row'} not found`)
}

E_AUTHORIZATION_FAILURE

当 bouncer 授权检查失败时，会抛出此异常。该异常是自处理的，并使用内容协商向客户端返回适当的错误响应。

状态码：403
自处理：是
翻译标识符：errors.E_AUTHORIZATION_FAILURE

import { errors as bouncerErrors } from '@adonisjs/bouncer'
if (error instanceof bouncerErrors.E_AUTHORIZATION_FAILURE) {
}

E_TOO_MANY_REQUESTS

当请求在一次给定时间内耗尽了所有允许的请求时，@adonisjs/rate-limiter 包会抛出此异常。该异常是自处理的，并使用内容协商向客户端返回适当的错误响应。

状态码：429
自处理：是
翻译标识符：errors.E_TOO_MANY_REQUESTS

import { errors as limiterErrors } from '@adonisjs/limiter'
if (error instanceof limiterErrors.E_TOO_MANY_REQUESTS) {
}

E_BAD_CSRF_TOKEN

当使用了 CSRF 保护的表单在未携带 CSRF 令牌的情况下提交，或者 CSRF 令牌无效时，会抛出此异常。

状态码：403
自处理：是
翻译标识符：errors.E_BAD_CSRF_TOKEN

import { errors as shieldErrors } from '@adonisjs/shield'
if (error instanceof shieldErrors.E_BAD_CSRF_TOKEN) {
}

E_BAD_CSRF_TOKEN 异常是自处理的，用户会被重定向回表单，你可以通过闪现消息访问该错误。

@error('E_BAD_CSRF_TOKEN')
  <p>{{ message }}</p>
@end

E_OAUTH_MISSING_CODE

当 OAuth 服务在重定向期间未提供 OAuth code 时，@adonisjs/ally 包会抛出此异常。

如果你在调用 .accessToken 或 .user 方法之前处理错误，就可以避免此异常。

状态码：500
自处理：否

import { errors as allyErrors } from '@adonisjs/bouncer'
if (error instanceof allyErrors.E_OAUTH_MISSING_CODE) {
}

E_OAUTH_STATE_MISMATCH

当重定向期间定义的 CSRF state 缺失时，@adonisjs/ally 包会抛出此异常。

如果你在调用 .accessToken 或 .user 方法之前处理错误，就可以避免此异常。

状态码：400
自处理：否

import { errors as allyErrors } from '@adonisjs/bouncer'
if (error instanceof allyErrors.E_OAUTH_STATE_MISMATCH) {
}

E_UNAUTHORIZED_ACCESS

当某个认证守卫无法对请求进行身份认证时，会抛出此异常。该异常是自处理的，并使用内容协商向客户端返回适当的错误响应。

状态码：401
自处理：是
翻译标识符：errors.E_UNAUTHORIZED_ACCESS

import { errors as authErrors } from '@adonisjs/auth'
if (error instanceof authErrors.E_UNAUTHORIZED_ACCESS) {
}

E_INVALID_CREDENTIALS

当 auth finder 无法校验用户凭据时，会抛出此异常。该异常是自处理的，并使用内容协商向客户端返回适当的错误响应。

状态码：400
自处理：是
翻译标识符：errors.E_INVALID_CREDENTIALS

import { errors as authErrors } from '@adonisjs/auth'
if (error instanceof authErrors.E_INVALID_CREDENTIALS) {
}

E_CANNOT_LOOKUP_ROUTE

当你尝试使用 URL 构建器为路由创建 URL 时，会抛出此异常。

状态码：500
自处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_CANNOT_LOOKUP_ROUTE) {
  // 处理错误
}

E_HTTP_EXCEPTION

E_HTTP_EXCEPTION 是一个通用的异常，用于在 HTTP 请求期间抛出错误。你可以直接使用此异常，或者创建一个继承自它的自定义异常。

状态码：在抛出异常时定义
自处理：是

抛出异常

import { errors } from '@adonisjs/core'

throw errors.E_HTTP_EXCEPTION.invoke(
  {
    errors: ['Cannot process request']
  },
  422
)

处理异常

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_HTTP_EXCEPTION) {
  // 处理错误
}

E_HTTP_REQUEST_ABORTED

E_HTTP_REQUEST_ABORTED 是 E_HTTP_EXCEPTION 异常的子类。该异常由 response.abort 方法抛出。

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_HTTP_REQUEST_ABORTED) {
  // 处理错误
}

E_INSECURE_APP_KEY

当 appKey 的长度小于 16 个字符时，会抛出此异常。你可以使用 generate ace 命令生成一个安全的应用密钥。

状态码：500
自处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_INSECURE_APP_KEY) {
  // 处理错误
}

E_MISSING_APP_KEY

当 appKey 属性未在 config/app.ts 文件中定义时，会抛出此异常。默认情况下，appKey 的值由 APP_KEY 环境变量设置。

状态码：500
自处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_MISSING_APP_KEY) {
  // 处理错误
}

E_INVALID_ENV_VARIABLES

当一个或多个环境变量未能通过校验时，会抛出此异常。可以使用 error.help 属性访问详细的校验错误。

状态码：500
自处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_INVALID_ENV_VARIABLES) {
  console.log(error.help)
}

E_MISSING_COMMAND_NAME

当某个命令未定义 commandName 属性或其值为空字符串时，会抛出此异常。

状态码：500
自处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_MISSING_COMMAND_NAME) {
  console.log(error.commandName)
}

E_COMMAND_NOT_FOUND

当 Ace 无法找到某个命令时，会抛出此异常。

状态码：404
自处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_COMMAND_NOT_FOUND) {
  console.log(error.commandName)
}

E_MISSING_FLAG

当执行命令时未传递某个必需的 CLI 标志时，会抛出此异常。

状态码：500
自处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_MISSING_FLAG) {
  console.log(error.commandName)
}

E_MISSING_FLAG_VALUE

当尝试执行命令而未给某个非布尔类型的 CLI 标志提供任何值时，会抛出此异常。

状态码：500
自处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_MISSING_FLAG_VALUE) {
  console.log(error.commandName)
}

E_MISSING_ARG

当执行命令时未定义必需的命令参数时，会抛出此异常。

状态码：500
自处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_MISSING_ARG) {
  console.log(error.commandName)
}

E_MISSING_ARG_VALUE

当执行命令时未定义某个必需命令参数的值时，会抛出此异常。

状态码：500
自处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_MISSING_ARG_VALUE) {
  console.log(error.commandName)
}

E_UNKNOWN_FLAG

当执行命令时使用了未知的 CLI 标志时，会抛出此异常。

状态码：500
自处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_UNKNOWN_FLAG) {
  console.log(error.commandName)
}

E_INVALID_FLAG

当为 CLI 标志提供的值无效时会抛出此异常——例如，向一个接受数值的标志传递了字符串值。

状态码：500
自处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_INVALID_FLAG) {
  console.log(error.commandName)
}

E_MULTIPLE_REDIS_SUBSCRIPTIONS

当你尝试多次订阅给定的 pub/sub 频道时，@adonisjs/redis 包会抛出此异常。

状态码：500
自处理：否

import { errors as redisErrors } from '@adonisjs/redis'
if (error instanceof redisErrors.E_MULTIPLE_REDIS_SUBSCRIPTIONS) {
}

E_MULTIPLE_REDIS_PSUBSCRIPTIONS

当你尝试多次订阅给定的 pub/sub 模式时，@adonisjs/redis 包会抛出此异常。

状态码：500
自处理：否

import { errors as redisErrors } from '@adonisjs/redis'
if (error instanceof redisErrors.E_MULTIPLE_REDIS_PSUBSCRIPTIONS) {
}

E_MAIL_TRANSPORT_ERROR

当无法使用给定的传输方式发送电子邮件时，@adonisjs/mail 包会抛出此异常。通常，当电子邮件服务的 HTTP API 返回非 200 的 HTTP 响应时会发生这种情况。

你可以使用 error.cause 属性访问网络请求错误。cause 属性是 got（npm 包）返回的错误对象。

状态码：400
自处理：否

import { errors as mailErrors } from '@adonisjs/mail'
if (error instanceof mailErrors.E_MAIL_TRANSPORT_ERROR) {
  console.log(error.cause)
}

E_SESSION_NOT_MUTABLE

当 session 存储以只读模式初始化时，@adonisjs/session 包会抛出此异常。

状态码：500
自处理：否

import { errors as sessionErrors } from '@adonisjs/session'
if (error instanceof sessionErrors.E_SESSION_NOT_MUTABLE) {
  console.log(error.message)
}

E_SESSION_NOT_READY

当 session 存储尚未初始化时，@adonisjs/session 包会抛出此异常。当你未使用 session 中间件时会出现这种情况。

状态码：500
自处理：否

import { errors as sessionErrors } from '@adonisjs/session'
if (error instanceof sessionErrors.E_SESSION_NOT_READY) {
  console.log(error.message)
}

参考资料

事件