runZonedGuarded无法捕获同路由下Dio抛出的异常问题

问题原因 #

同路由下的API调用多触发自Widget生命周期（如initState、GetX Controller的onInit）或同步代码启动的异步任务，这类异常会被Flutter框架的FlutterError机制优先拦截，不会进入runZonedGuarded的错误回调；而页面跳转后的API调用通常来自用户交互事件（如按钮点击），这类异步任务的执行上下文属于runZonedGuarded创建的Zone，因此异常能被正常捕获。

此外，若调用request方法时局部使用try/catch包裹且未重新抛出异常，也会导致异常无法冒泡到runZonedGuarded。

解决方案 #

1. 同步FlutterError与runZonedGuarded的错误处理 #

在runZonedGuarded内部配置FlutterError.onError，将Flutter框架捕获的异常转发到统一错误处理函数：

Future<void> main() async {
  runZonedGuarded<Future<void>>(() async {
    await dotenv.load(fileName: ".env");
    WidgetsFlutterBinding.ensureInitialized();
    
    // 将Flutter捕获的异常转发到统一处理逻辑
    FlutterError.onError = (FlutterErrorDetails details) {
      asyncErrorHandler(details.exception, details.stack);
    };
    
    initServices();
    runApp(App());
  }, asyncErrorHandler);
}

2. 绑定异步任务到目标Zone #

对于Widget生命周期中发起的异步任务，显式用Zone.current.run包裹，确保异常进入runZonedGuarded的处理流程：

// 示例：GetX Controller的onInit中使用
@override
void onInit() {
  super.onInit();
  Zone.current.run(() async {
    await _fetchData(); // 此处API异常会被runZonedGuarded捕获
  });
}

Future<void> _fetchData() async {
  await dio.request(RequestType.GET, "/api/data");
}

3. 规范局部try/catch的使用 #

避免不必要的局部try/catch，若必须做局部处理，记得重新抛出异常：

// 错误示例：局部捕获后未重新抛出
void _fetchData() async {
  try {
    await dio.request(...);
  } catch(e) {
    // 仅局部处理，未向上传递异常
  }
}

// 正确示例：局部处理后重新抛出
void _fetchData() async {
  try {
    await dio.request(...);
  } catch(e) {
    // 局部处理逻辑（如日志）
    rethrow; // 让上层runZonedGuarded继续处理
  }
}

4. 优化Dio异常处理逻辑（可选） #

将异常处理移至Dio拦截器中，避免在request方法中嵌套try/catch，简化异常传递路径：

class ErrorInterceptor extends Interceptor {
  @override
  void onError(DioException err, ErrorInterceptorHandler handler) {
    if (err.response == null) {
      handler.reject(NetworkException());
      return;
    }

    switch (err.response?.statusCode) {
      case 400:
        handler.reject(ValidationException(data: err.response?.data));
        break;
      case 401:
        handler.reject(UnauthenticatedException());
        break;
      case 403:
        handler.reject(ForbiddenException());
        break;
      case 426:
        handler.reject(UpgradeException(data: err.response?.data));
        break;
      case 429:
        handler.reject(TooManyRequestsException());
        break;
      default:
        handler.reject(APIException());
    }
  }
}

// 初始化Dio时添加拦截器
final Dio _client = Dio()..interceptors.add(ErrorInterceptor());

内容的提问来源于stack exchange，提问作者Mohannad Jamal