HarmonyOS 鸿蒙Next ArkTS API 网络错误处理总结

核心错误类型与说明

• NETWORK_UNAVAILABLE

  • 触发条件：设备无可用网络连接
  • 处理建议：
    • 检查设备网络开关状态
    • 验证Wi-Fi/移动数据连接
    • 调用hasDefaultNet()检测网络状态
    • 提供用户引导界面

• DNS_RESOLUTION_FAILED

  • 典型场景：域名解析失败
  • 根因分析：
    • DNS服务器不可达
    • 域名不存在或配置错误
    • 本地DNS缓存污染
  • 解决方案：
    • 尝试使用IP直连（如有备用IP）
    • 切换DNS服务器（如8.8.8.8）
    • 实现本地hosts文件映射

• CONNECTION_TIMEOUT

  • 阈值范围：默认10-30秒（可配置）
  • 优化方向：

    // 设置自定义超时
    httpRequest.setExtraOptions({
      connectTimeout: 15000,  // 15秒连接超时
      readTimeout: 30000      // 30秒读取超时
    });
    

  • 重试策略：实现指数退避重试机制

• SSL_HANDSHAKE_ERROR

  • 安全相关子类：
    • CERTIFICATE_EXPIRED（证书过期）
    • UNTRUSTED_CA（未授信CA签发）
    • DOMAIN_MISMATCH（域名不匹配）
  • 特殊处理模式：

    // 开发环境绕过验证（生产禁用！）
    httpRequest.setExtraOptions({
      usingProtocol: http.HttpProtocol.HTTP2,
      sslOptions: {
        trustedCa: this.getContext().resourceManager.getRawFile('user_ca.pem'),
        validateCertificate: false // 慎用！
      }
    });
    

高级错误处理策略

• 错误传播机制

  • 通过AsyncCallback或Promise传递错误对象
  • 错误对象包含：

    {
      code: number,       // 标准错误码
      message: string,    // 可读错误描述
      stacktrace?: string // 调用栈信息（调试模式）
    }
    

• 网络状态监听

  // 注册网络状态监听器
  netConnection.on('netAvailable', (data) => {
    console.log("网络恢复可用");
    this.retryPendingRequests();
  });
  
  // 资源释放时机
  netConnection.off('netAvailable');
  

• 自定义错误映射

  const CUSTOM_ERROR_MAP = {
    1001: 'SESSION_EXPIRED',
    1002: 'API_QUOTA_LIMIT'
  };
  
  function handleError(error) {
    if(CUSTOM_ERROR_MAP[error.code]) {
      showToast(CUSTOM_ERROR_MAP[error.code]);
    } else {
      // 处理标准网络错误
    }
  }
  

最佳实践建议

• 分级错误处理

• 关键重试策略

  • 首次失败：立即重试（1秒内）
  • 二次失败：延时重试（3秒 + 随机抖动）
  • 三次失败：指数退避（最大重试3次）
  • 最终失败：展示友好错误页

• 诊断工具集成

  // 网络诊断示例
  import diag from '[@ohos](/user/ohos).net.diag';
  
  diag.startNetDiag({
    netType: diag.NetType.NET_TYPE_WIFI,
    callback: (result) => {
      console.log(`诊断结果: ${JSON.stringify(result)}`);
    }
  });
  

• 离线模式支持

  • 使用[@ohos](/user/ohos).data.storage缓存关键数据
  • 实现请求队列持久化存储
  • 网络恢复后自动同步机制

特殊场景处理

• 弱网环境优化

  • 启用HTTP/3协议（QUIC）
  • 数据压缩传输（GZIP/Brotli）
  • 分块加载/增量更新

• 证书固定实践

  httpRequest.setExtraOptions({
    sslOptions: {
      pinners: [
        {
          hostname: 'api.example.com',
          pins: [
            'sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAA=',
            'sha256/BBBBBBBBBBBBBBBBBBBBBBBBBB='
          ]
        }
      ]
    }
  });
  

• 协议升级策略

  // 支持协议优先级配置
  httpRequest.setExtraOptions({
    usingProtocol: [
      http.HttpProtocol.HTTP3,
      http.HttpProtocol.HTTP2,
      http.HttpProtocol.HTTP1_1
    ]
  });
  

错误监控体系

• 关键监控指标

  • 错误率/成功率（按API端点）
  • 地域/运营商维度分布
  • 设备类型/OS版本分布

• 自动化报警规则

  • 连续错误率>5%（5分钟窗口）
  • 特定错误码突增
  • 关键API完全不可用

重要提示：生产环境必须实现错误日志加密存储，禁止明文记录敏感数据（如认证令牌、用户隐私信息）。建议使用[@ohos](/user/ohos).security.huks进行日志加密处理。