异常


【Exceptions】

任何 Node-API 函数调用都可能导致挂起的 JavaScript 异常。对于任何 API 函数都是如此,即使是那些可能不会触发 JavaScript 执行的函数。

【Any Node-API function call may result in a pending JavaScript exception. This is the case for any of the API functions, even those that may not cause the execution of JavaScript.】

如果函数返回的 napi_statusnapi_ok,则表示没有挂起的异常,也不需要采取其他操作。如果返回的 napi_status 不是 napi_oknapi_pending_exception,为了尝试恢复并继续执行,而不是立即返回,必须调用 napi_is_exception_pending 来确定是否有异常挂起。

【If the napi_status returned by a function is napi_ok then no exception is pending and no additional action is required. If the napi_status returned is anything other than napi_ok or napi_pending_exception, in order to try to recover and continue instead of simply returning immediately, napi_is_exception_pending must be called in order to determine if an exception is pending or not.】

在很多情况下,当调用 Node-API 函数且已存在未处理的异常时,该函数会立即返回 napi_statusnapi_pending_exception。然而,并非所有函数都是这样。Node-API 允许调用其中一部分函数,以便在返回 JavaScript 之前进行一些最小的清理。在这种情况下,napi_status 会反映函数的执行状态,而不会反映之前未处理的异常。为了避免混淆,应在每次函数调用后检查错误状态。

【In many cases when a Node-API function is called and an exception is already pending, the function will return immediately with a napi_status of napi_pending_exception. However, this is not the case for all functions. Node-API allows a subset of the functions to be called to allow for some minimal cleanup before returning to JavaScript. In that case, napi_status will reflect the status for the function. It will not reflect previous pending exceptions. To avoid confusion, check the error status after every function call.】

当异常悬而未决时,可以采用两种方法之一。

【When an exception is pending one of two approaches can be employed.】

第一种方法是进行任何适当的清理,然后返回,以便执行可以回到 JavaScript。作为回到 JavaScript 过渡的一部分,异常将在原生方法被调用的 JavaScript 代码处抛出。在异常挂起期间,大多数 Node-API 调用的行为是未定义的,很多调用会简单地返回 napi_pending_exception,因此应尽量少做操作,然后返回到 JavaScript 以处理异常。

【The first approach is to do any appropriate cleanup and then return so that execution will return to JavaScript. As part of the transition back to JavaScript, the exception will be thrown at the point in the JavaScript code where the native method was invoked. The behavior of most Node-API calls is unspecified while an exception is pending, and many will simply return napi_pending_exception, so do as little as possible and then return to JavaScript where the exception can be handled.】

第二种方法是尝试处理异常。会有一些情况,本地代码可以捕获异常,采取适当的措施,然后继续执行。这仅建议在特定情况下使用,即已知异常可以安全处理。在这些情况下,可以使用 napi_get_and_clear_last_exception 来获取并清除异常。成功时,result 将包含最近抛出的 JavaScript Object 的句柄。如果在获取异常后确定无法处理该异常,可以使用 napi_throw 重新抛出异常,其中 error 是要抛出的 JavaScript 值。

【The second approach is to try to handle the exception. There will be cases where the native code can catch the exception, take the appropriate action, and then continue. This is only recommended in specific cases where it is known that the exception can be safely handled. In these cases napi_get_and_clear_last_exception can be used to get and clear the exception. On success, result will contain the handle to the last JavaScript Object thrown. If it is determined, after retrieving the exception, the exception cannot be handled after all it can be re-thrown it with napi_throw where error is the JavaScript value to be thrown.】

以下工具函数也可用,以防原生代码需要抛出异常或确定 napi_value 是否是 JavaScript Error 对象的实例:napi_throw_errornapi_throw_type_errornapi_throw_range_errornode_api_throw_syntax_errornapi_is_error

【The following utility functions are also available in case native code needs to throw an exception or determine if a napi_value is an instance of a JavaScript Error object: napi_throw_error, napi_throw_type_error, napi_throw_range_error, node_api_throw_syntax_error and napi_is_error.】

如果本地代码需要创建一个 Error 对象,还可以使用以下实用函数:napi_create_errornapi_create_type_errornapi_create_range_errornode_api_create_syntax_error,其中 result 是引用新创建的 JavaScript Error 对象的 napi_value

【The following utility functions are also available in case native code needs to create an Error object: napi_create_error, napi_create_type_error, napi_create_range_error and node_api_create_syntax_error, where result is the napi_value that refers to the newly created JavaScript Error object.】

Node.js 项目正在为所有内部生成的错误添加错误代码。目标是让应用在进行所有错误检查时使用这些错误代码。相关的错误信息将保留,但仅用于记录和显示,预期这些信息可能会变化而不遵循语义化版本控制(SemVer)。为了支持 Node-API 的这一模型,无论是在内部功能还是模块特定功能中(这是良好实践),throw_create_ 函数都接受一个可选的 code 参数,该参数是要添加到错误对象的错误代码字符串。如果可选参数为 NULL,则错误不会关联任何代码。如果提供了代码,错误关联的名称也会更新为:

【The Node.js project is adding error codes to all of the errors generated internally. The goal is for applications to use these error codes for all error checking. The associated error messages will remain, but will only be meant to be used for logging and display with the expectation that the message can change without SemVer applying. In order to support this model with Node-API, both in internal functionality and for module specific functionality (as its good practice), the throw_ and create_ functions take an optional code parameter which is the string for the code to be added to the error object. If the optional parameter is NULL then no code will be associated with the error. If a code is provided, the name associated with the error is also updated to be:】

originalName [code] 

其中 originalName 是与错误相关的原始名称,code 是提供的代码。例如,如果代码是 'ERR_ERROR_1' 并且正在创建一个 TypeError,则名称将是:

【where originalName is the original name associated with the error and code is the code that was provided. For example, if the code is 'ERR_ERROR_1' and a TypeError is being created the name will be:】

TypeError [ERR_ERROR_1]