HarmonyOS实战开发：ArkTS编程Node-API接口处理异常错误

简介

使用Node-API接口进行错误处理开发，使得在Node-API模块中能够更好地管理和响应错误情况。通过合理使用这些函数，可以提高模块的稳定性和可靠性。

基本概念

在ArkTS编程中，异常和错误是常见的概念。异常表示发生了某种意外情况，而错误则指示程序无法正确执行某些操作。Node-API提供了一系列方法来帮助开发者在Node-API模块中处理ArkTS中的异常和错误。下面是一些基本概念：

• 异常（Exception）：在程序执行过程中可能会出现的意外情况，可以是语法错误、运行时错误或逻辑错误，例如除以零或对未定义变量的操作。
• 错误（Error）：表示程序无法顺利执行某些操作，可以是由底层系统、API函数或开发者自定义的。
• 类型错误（Type Error）：表示操作或值的类型不符合预期的情况，通常是由于错误的数据类型导致的。
• 范围错误（Range Error）：表示一个值不在预期的范围内，例如对数组长度之外的索引进行访问。

这些基本概念在异常和错误处理中非常重要，开发者需要通过适当的方法来捕获、处理或向用户报告这些异常和错误，以确保程序的稳定性和正确性。Node-API提供的方法可以帮助开发者在Node-API模块中处理ArkTS中的异常和错误。

场景和功能介绍

以下Node-API接口主要用于与ArkTS交互时处理错误和异常情况。他们的使用场景如下：

接口	描述
napi_create_error、napi_create_type_error、napi_create_range_error	在C/C++中需要创建一个错误对象时，可以使用这些函数。创建的错误对象可以使用napi_throw抛出到ArkTS
napi_throw	当在C/C++中出现了错误或异常情况时，通过使用napi_create_error或napi_get_last_error_info方法创建或获取ArkTS Error对象，使用该方法抛出已有的ArkTS Error对象。
napi_throw_error、napi_throw_type_error、napi_throw_range_error	当在C/C++中出现了错误或异常情况时，可以使用这些函数来抛出ArkTS中的异常。
napi_is_error	检查一个napi_value是否代表一个错误对象时，可以使用这个函数。
napi_get_and_clear_last_exception	当你需要获取最近一次出现的异常，并将异常队列清空时，可以使用这个函数。
napi_is_exception_pending	当你需要判断是否有未处理的异常时，可以使用这个函数。
napi_fatal_error	当遇到严重错误或不可恢复的情况时，可以使用这个函数引发致命错误来立即终止进程。
napi_fatal_exception	抛出一个致命异常并终止进程, 同时产生相应的crash日志。

使用示例

Node-API接口开发流程参考使用Node-API实现跨语言交互开发流程，本文仅对接口对应C++及ArkTS相关代码进行展示。

napi_get_last_error_info

用于获取最后一次发生的错误信息，包括错误码、错误消息以及错误进栈信息，即使存在挂起的ArkTS异常，也可以调用此API。

cpp部分代码

#include "napi/native_api.h"
#include <assert.h>
static napi_value GetLastErrorInfo(napi_env env, napi_callback_info info)
{
    // 获取输入参数（这里以字符串message作为参数传入）
    size_t argc = 1;
    napi_value args[1] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
    // 将传入的字符串参数以napi_get_value_int32取出，主动制造错误
    int32_t value = 0;
    napi_status status = napi_get_value_int32(env, args[0], &value);
    // 接口使用错误，故返回值不为napi_ok
    assert(status != napi_ok);
    // 调用接口napi_get_last_error_info获取最后一次错误信息
    const napi_extended_error_info *errorInfo;
    napi_get_last_error_info(env, &errorInfo);
    // 取出错误码与接口调用错误后其返回值作比较
    assert(errorInfo->error_code == status);
    // 取出错误消息作为返回值带出去打印
    napi_value result = nullptr;
    napi_create_string_utf8(env, errorInfo->error_message, NAPI_AUTO_LENGTH, &result);
    return result;
}

接口声明

// index.d.ts
export const getLastErrorInfo: (str: string) => string;

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'
try {
  hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_last_error_info: %{public}s', testNapi.getLastErrorInfo('message'));
} catch (error) {
  hilog.error(0x0000, 'testTag', 'Test Node-API napi_get_last_error_info error: %{public}s', error);
}

napi_create_type_error

创建并获取一个带文本信息的ArkTS TypeError。

cpp部分代码

#include "napi/nat