**鸿蒙（HarmonyOS）中的 BusinessError 详解

BusinessError 是鸿蒙开发中用于 标准化业务错误信息 的核心对象，属于 @kit.BasicServicesKit 模块。它封装了错误码和错误描述，帮助开发者统一处理异步操作或系统 API 调用中的异常。

一、核心属性与方法

二、典型使用场景

1. 捕获 API 调用错误

import { BusinessError } from '@kit.BasicServicesKit';

async function scanBarcode() {
  try {
    const result = await scanBarcode.startScanForResult(getContext(this));
  } catch (err) {
    const error = err as BusinessError;
    if (error.code === 201) {
      console.log('用户取消了扫码操作');
    } else {
      console.error(`错误码: ${error.code}, 错误信息: ${error.message}`);
    }
  }
}

2. 自定义业务错误

// 定义错误码常量
enum CustomErrorCode {
  NETWORK_FAILURE = 1001,
  INVALID_DATA = 1002,
}

// 抛出自定义 BusinessError
function validateData(data: string) {
  if (!data) {
    throw { 
      code: CustomErrorCode.INVALID_DATA, 
      message: '数据不能为空' 
    } as BusinessError;
  }
}

三、常见系统错误码参考

四、错误处理最佳实践

1. 错误分类处理

catch (err) {
  const error = err as BusinessError;
  switch (error.code) {
    case 201:
      // 用户取消，无需处理
      break;
    case 401:
      // 参数错误，上报异常
      reportError(error);
      break;
    default:
      showToast(`操作失败：${error.message}`);
  }
}

2. 全局错误监控

// 注册全局错误监听
appManager.on('error', (error: BusinessError) => {
  logger.error(`全局捕获错误: ${error.code} - ${error.message}`);
});

3. 错误信息本地化

// 根据错误码映射多语言提示
function getErrorMessage(error: BusinessError): string {
  const i18nMap: Record<number, string> = {
    201: this.$t('error.userCancel'),
    401: this.$t('error.invalidParam')
  };
  return i18nMap[error.code] || error.message;
}

五、与 Error 对象的区别

六、调试技巧

1. 开启详细堆栈
   在 config.json 中启用开发模式：

   {
     "app": {
       "debug": true
     }
   }
   

2. 日志过滤
   使用 hilog 模块按错误码过滤日志：

   import { hilog } from '@kit.PerformanceAnalysisKit';
   hilog.error(0x0000, 'MyApp', `ErrorCode=${error.code}, Message=${error.message}`);
   

3. 错误码查询工具
   使用华为开发者工具（DevEco Studio）的 Error Code Lookup 功能，快速定位错误原因。

总结：
BusinessError 是鸿蒙错误处理体系的核心，通过标准化的错误码和消息，帮助开发者实现：

• 精准定位问题：通过 code 快速识别错误类型
• 统一错误处理：跨模块/API 的错误响应一致性
• 提升健壮性：分类处理可恢复错误与致命错误