异常

¥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_status 是 napi_ok，则没有异常挂起，也不需要额外的操作。如果返回的 napi_status 不是 napi_ok 或 napi_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_status 或 napi_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 可用于获取和清除异常。成功时，结果将包含最后抛出的 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_error、napi_throw_type_error、napi_throw_range_error、node_api_throw_syntax_error 和 napi_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_error、napi_create_type_error、napi_create_range_error 和 node_api_create_syntax_error，其中结果是指代新创建的 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_ 函数采用可选代码参数，该参数是要添加到错误中的代码字符串 目的。如果可选参数是 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] 拷贝