异常参考

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

E_ROUTE_NOT_FOUND

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

状态码：404
自我处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_ROUTE_NOT_FOUND) {
  // handle error
}

E_ROW_NOT_FOUND

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

状态码：404
自我处理：否

import { errors as lucidErrors } from '@adonisjs/lucid'
if (error instanceof lucidErrors.E_ROW_NOT_FOUND) {
  // handle error
  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 异常是自我处理的，用户会被重定向回表单，你可以使用 flash 消息来访问该错误。

@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/ally'
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/ally'
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

当身份验证查找器无法验证用户凭据时抛出该异常。该异常会被处理并使用内容协商向客户端返回适当的错误响应。

状态码：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) {
  // handle error
}

E_HTTP_EXCEPTION

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

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

// title: Throw exception
import { errors } from '@adonisjs/core'

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

// title: Handle exception
import { errors } from '@adonisjs/core'
if (error instanceof errors.E_HTTP_EXCEPTION) {
  // handle error
}

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) {
  // handle error
}

E_INSECURE_APP_KEY

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

状态码：500
自我处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_INSECURE_APP_KEY) {
  // handle error
}

E_MISSING_APP_KEY

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

状态码：500
自我处理：否

import { errors } from '@adonisjs/core'
if (error instanceof errors.E_MISSING_APP_KEY) {
  // handle error
}

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

当会话存储以只读模式初始化时，@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

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

状态码：500
自我处理：否

import { errors as sessionErrors } from '@adonisjs/session'

if (error instanceof sessionErrors.E_SESSION_NOT_READY) {
  console.log(error.message)
}

E_MISSING_METAFILE_PATTERN

当 metaFile 中缺少 pattern 属性时抛出该异常。

状态码：500
自我处理：否

import { errors } from '@adonisjs/core'

if (error instanceof errors.E_MISSING_METAFILE_PATTERN) {
  console.log(error.message)
}

E_MISSING_PRELOAD_FILE

当在 adonisrc.ts 文件中注册的预加载文件无法找到时抛出该异常。

状态码：500
自我处理：否

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

E_INVALID_PRELOAD_FILE

当预加载的 file 属性不是函数时抛出该异常。

状态码：500
自我处理：否

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

E_MISSING_PROVIDER_FILE

当在 adonisrc.ts 文件中注册的服务提供者文件无法找到时抛出该异常。

状态码：500
自我处理：否

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

E_INVALID_PROVIDER

当提供者的 file 属性不是函数时抛出该异常。

状态码：500
自我处理：否

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

E_MISSING_SUITE_NAME

当 adonisrc.ts 文件中的测试套件配置缺少必需的 name 属性时抛出该异常。

状态码：500
自我处理：否

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

E_MISSING_SUITE_FILES

当 adonisrc.ts 文件中的测试套件配置缺少必需的 files 属性时抛出该异常。

状态码：500
自我处理：否

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

E_UNKNOWN_ASSEMBLER_HOOK

当在 adonisrc.ts 文件中定义了未知的汇编器钩子时抛出该异常。

状态码：500
自我处理：否

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

E_INVALID_HOOKS_VALUE

当 adonisrc.ts 文件中的 hooks 配置不是惰性导入数组时抛出该异常。

状态码：500
自我处理：否

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

E_INVALID_PRESETS_VALUE

当 presets 配置不是预设函数数组时抛出该异常。

状态码：500
自我处理：否

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

E_INVALID_PRESET_FUNCTION

当预设未定义为函数时抛出该异常。

状态码：500
自我处理：否

import { errors } from '@adonisjs/core'

if (error instanceof errors.E_INVALID_PRESET_FUNCTION) {
  console.log(error.message)
}

E_PRESET_EXECUTION_ERROR

当预设执行期间发生错误时抛出该异常。

状态码：500
自我处理：否

import { errors } from '@adonisjs/core'

if (error instanceof errors.E_PRESET_EXECUTION_ERROR) {
  console.log(error.message)
  console.log(error.cause)
}

E_INVALID_ENV_VARIABLES

当根据 start/env.ts 文件中定义的规则，一个或多个环境变量无效时抛出该异常。

状态码：500
自我处理：否

import { errors } from '@adonisjs/core'

if (error instanceof errors.E_INVALID_ENV_VARIABLES) {
  console.log(error.message)
  console.log(error.help)
}

E_IDENTIFIER_ALREADY_DEFINED

当尝试覆盖某个 Env 标识符的实现时抛出该异常。请考虑改用 Env.defineIdentifierIfMissing 方法。

状态码：500
自我处理：否

import { errors } from '@adonisjs/core'

if (error instanceof errors.E_IDENTIFIER_ALREADY_DEFINED) {
  console.log(error.message)
}

辅助函数 AdonisJS 将其实用程序打包进 helpers 模块，并使其对你的应用代码可用。