全栈若城头像
HarmonyOS7 全局异常怎么兜底才靠谱?错误处理和降级架构这样搭封面图

HarmonyOS7 全局异常怎么兜底才靠谱?错误处理和降级架构这样搭

前言

你有没有遇到过这种情况:用户在某个页面点了个按钮,接口超时了,页面直接白屏,然后应用闪退。查日志发现是一个未捕获的 Promise rejection。

这类问题在鸿蒙应用里也很常见。错误处理如果只是到处写 try-catch,不仅代码臃肿,还容易漏掉。这篇文章我来搭一套全局错误处理架构,从捕获、分类、降级到上报,一条龙解决。

鸿蒙应用的错误分类

先理清楚错误有哪些类型,不同类型处理方式不一样:

  • 同步错误:代码逻辑出错,比如空指针、数组越界。这类最致命,通常会导致页面崩溃。

A clean Notion-style vertical list layout titled '

  • 异步错误:Promise rejection 没被 catch,或者 async 函数里抛了异常。
  • 网络错误:超时、断网、服务端 5xx。这类最常见,也是最能优化体验的地方。
  • 系统错误:权限被拒、存储空间不足、传感器不可用。这类需要引导用户去设置。

全局错误捕获

鸿蒙提供了 globalThis 上的错误监听能力,我在应用启动时就注册好:

// entry/src/main/ets/entryability/EntryAbility.ts
import { ErrorHandler } from '../common/ErrorHandler';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 注册全局错误捕获
    ErrorHandler.setup();
    
    // 初始化日志、网络层等
    Logger.info('App', '应用启动');
  }
}

ErrorHandler 是核心类,负责注册各类错误监听并分发处理:

import { ErrorReporter } from './ErrorReporter';
import { ErrorMessageMapper } from './ErrorMessageMapper';

export interface AppError {
  type: 'sync' | 'async' | 'network' | 'system';
  code: number;
  message: string;
  stack?: string;
  timestamp: number;
  pageName?: string;
}

export class ErrorHandler {
  private static handlers: Array<(error: AppError) => void> = [];

  static setup(): void {
    // 捕获未处理的同步错误
    globalThis.onerror = (msg: string, source: string, lineno: number, colno: number, error: Error) => {
      const appError: AppError = {
        type: 'sync',
        code: -1,
        message: msg,
        stack: error?.stack,
        timestamp: Date.now()
      };
      ErrorHandler.dispatch(appError);
    };

    // 捕获未处理的 Promise rejection
    globalThis.onunhandledrejection = (event: PromiseRejectionEvent) => {
      const appError: AppError = {
        type: 'async',
        code: -2,
        message: String(event.reason),
        stack: event.reason?.stack,
        timestamp: Date.now()
      };
      ErrorHandler.dispatch(appError);
      // 阻止默认行为,防止应用崩溃
      event.preventDefault?.();
    };

    Logger.info('ErrorHandler', '全局错误捕获已注册');
  }

  // 注册错误处理回调
  static addHandler(handler: (error: AppError) => void): void {
    this.handlers.push(handler);
  }

  // 分发错误到所有处理器
  private static dispatch(error: AppError): void {
    // 先上报
    ErrorReporter.report(error);

    // 再通知所有注册的处理器
    for (const handler of this.handlers) {
      try {
        handler(error);
      } catch (e) {
        console.error('错误处理器自身出错', e);
      }
    }
  }

  // 手动上报错误(用于业务层主动上报)
  static report(code: number, message: string, type: AppError['type'] = 'sync'): void {
    const appError: AppError = {
      type, code, message,
      timestamp: Date.now()
    };
    this.dispatch(appError);
  }
}

A structured Notion-style process diagram showing

错误降级策略:三层兜底

核心思路是 接口失败 → 缓存兜底 → 兜底 UI,尽量不让用户看到白屏。

export type DataState<T> =
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'cache'; data: T; stale: boolean }
  | { status: 'error'; error: AppError };

export class DataFetcher<T> {
  private cacheKey: string;

  constructor(cacheKey: string) {
    this.cacheKey = cacheKey;
  }

  async fetch(
    requestFn: () => Promise<T>,
    options?: { useCache?: boolean; cacheTTL?: number }
  ): Promise<DataState<T>> {
    try {
      const data = await requestFn();
      // 请求成功,同时更新缓存
      if (options?.useCache !== false) {
        await this.saveCache(data);
      }
      return { status: 'success', data };
    } catch (error) {
      // 请求失败,尝试缓存兜底
      if (options?.useCache !== false) {
        const cached = await this.loadCache();
        if (cached) {
          Logger.warn('DataFetcher', `${this.cacheKey} 接口失败,使用缓存兜底`);
          return { status: 'cache', data: cached.data, stale: true };
        }
      }
      // 缓存也没有,返回错误状态
      return {
        status: 'error',
        error: error as AppError
      };
    }
  }

  private async saveCache(data: T): Promise<void> {
    const context = getContext() as common.UIAbilityContext;
    const prefs = await preferences.getPreferences(context, 'data_cache');
    await prefs.put(this.cacheKey, JSON.stringify({
      data,
      timestamp: Date.now()
    }));
    await prefs.flush();
  }

  private async loadCache(): Promise<{ data: T; stale: boolean } | null> {
    try {
      const context = getContext() as common.UIAbilityContext;
      const prefs = await preferences.getPreferences(context, 'data_cache');
      const raw = prefs.getSync(this.cacheKey, '') as string;
      if (!raw) return null;
      const parsed = JSON.parse(raw);
      return { data: parsed.data as T, stale: true };
    } catch {
      return null;
    }
  }
}

A Notion-style three-tier pyramid or stack diagram

错误码 → 用户可读文案

直接给用户看 “Error code: 40001” 没有任何意义。搞一个映射表,把错误码翻译成人话:

export class ErrorMessageMapper {
  private static messages: Map<number, string> = new Map([
    [10001, '网络连接失败,请检查网络设置'],
    [10002, '请求超时,请稍后重试'],
    [10003, '服务器开小差了,请稍后再试'],
    [20001, '登录已过期,请重新登录'],
    [20002, '账号在其他设备登录'],
    [20003, '账号已被禁用'],
    [30001, '内容不存在或已被删除'],
    [30002, '没有权限执行此操作'],
    [40001, '存储空间不足,请清理后重试'],
    [40002, '相机权限未开启,请在设置中允许'],
  ]);

  static getMessage(code: number): string {
    return this.messages.get(code) ?? '出了点问题,请稍后重试';
  }

  // 注册新的错误码映射
  static register(code: number, message: string): void {
    this.messages.set(code, message);
  }
}

ErrorBoundary 组件:错误隔离 + 降级 UI

借鉴 React 的 ErrorBoundary 思路,我实现了一个 ArkUI 版本的错误边界组件。核心是用 @State 控制显示状态,出错了就展示兜底 UI,不影响其他模块。

@Component
export struct ErrorBoundary {
  @State hasError: boolean = false;
  @State errorMessage: string = '';
  @State errorDetail: string = '';
  @Prop fallbackText: string = '加载失败';
  onRetry?: () => void;
  @BuilderParam content: () => void;

  aboutToAppear(): void {
    ErrorHandler.addHandler((error: AppError) => {
      // 可以根据 pageName 判断是不是当前区域的错误
      this.hasError = true;
      this.errorMessage = ErrorMessageMapper.getMessage(error.code);
      this.errorDetail = error.message;
    });
  }

  build() {
    if (this.hasError) {
      Column() {
        Image($r('app.media.ic_error'))
          .width(80)
          .height(80)
          .margin({ bottom: 16 })

        Text(this.errorMessage)
          .fontSize(16)
          .fontColor('#333333')
          .margin({ bottom: 8 })

        Text('点击重试')
          .fontSize(14)
          .fontColor('#007DFF')
          .onClick(() => {
            this.hasError = false;
            this.onRetry?.();
          })
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
      .alignItems(HorizontalAlign.Center)
    } else {
      Column() {
        this.content()
      }
    }
  }
}

使用方式很简单,把可能出错的区域包起来:

@Entry
@Component
struct ProductPage {
  @State products: Product[] = [];

  build() {
    Column() {
      // 头部不参与错误隔离
      HeaderBar({ title: '商品列表' })

      // 列表区域用 ErrorBoundary 包裹
      ErrorBoundary({
        onRetry: () => this.loadProducts(),
        content: () => {
          List() {
            ForEach(this.products, (item: Product) => {
              ListItem() { ProductCard({ product: item }) }
            })
          }
        }
      })
    }
  }

  async loadProducts() {
    const fetcher = new DataFetcher<Product[]>('products');
    const result = await fetcher.fetch(
      () => httpService.get<Product[]>('/products'),
      { useCache: true }
    );

    switch (result.status) {
      case 'success':
      case 'cache':
        this.products = result.data;
        if (result.status === 'cache') {
          // 提示用户数据可能不是最新的
          promptAction.showToast({ message: '当前显示离线数据' });
        }
        break;
      case 'error':
        ErrorHandler.report(result.error.code, result.error.message, 'network');
        break;
    }
  }
}

错误上报

最后别忘了把错误发到服务端,方便排查问题。上报的时候带上设备信息、页面路径、用户 ID 这些上下文:

export class ErrorReporter {
  private static reportUrl: string = 'https://log.example.com/report';
  private static queue: AppError[] = [];
  private static batchSize: number = 10;

  static report(error: AppError): void {
    this.queue.push(error);
    if (this.queue.length >= this.batchSize) {
      this.flush();
    }
  }

  static async flush(): Promise<void> {
    if (this.queue.length === 0) return;
    
    const batch = this.queue.splice(0);
    const deviceInfo = device.getCurrent();
    const reportData = {
      errors: batch,
      device: deviceInfo.productModel,
      osVersion: deviceInfo.osFullName,
      appVersion: '1.0.0',
      timestamp: Date.now()
    };

    try {
      // 上报请求本身不能再触发错误上报,否则会死循环
      await http.createHttp().request(this.reportUrl, {
        method: http.RequestMethod.POST,
        extraData: reportData,
        connectTimeout: 5000,
      });
    } catch {
      // 上报失败就丢掉,不能影响主流程
    }
  }
}

一些心得

搞完这套错误处理架构之后,我的项目稳定性提升了很多。几个关键点:

降级比报错重要。 用户不关心你的接口为什么挂了,他们只想知道还能不能用。缓存兜底 + 提示"离线数据",体验比白屏好太多了。

错误码映射表要维护好。 每加一个新接口就检查一下错误码是否有对应文案,别让用户看到 “undefined” 或 “Error: null”。

错误上报别阻塞主线程。 用队列批量上报,失败了就静默丢弃。上报请求本身绝对不能触发二次上报,不然一个网络抖动就能把日志打爆。

转载自 CSDN-专业IT技术社区

原文链接:https://blog.csdn.net/qq_33681891/article/details/162408005

文章来源转载

评论

评论列表

微信小程序
QQ小程序

关于作者

点赞数:0
关注数:0
粉丝:0
文章:0
关注标签:0
加入于:--