欢迎加入开源鸿蒙跨平台社区：
https://openharmonycrossplatform.csdn.net

Flutter dio 在 OpenHarmony 上的网络异常处理适配实践

前言

在 Flutter 跨平台开发过程中，网络请求是应用中最核心的功能之一。
在将 Flutter 项目迁移到 OpenHarmony 平台后，我发现部分原本在 Android 上运行正常的网络请求，在鸿蒙设备中会出现超时、证书校验失败以及 SocketException 等问题。

本文结合实际项目经验，介绍如何使用 dio 完成 OpenHarmony 平台下的网络请求适配，并总结常见网络异常的解决方案，希望能够帮助开发者少踩一些坑。

---

一、项目背景

本次实践项目采用：

• Flutter 3.x

• dio 5.x

• Flutter for OpenHarmony

项目主要功能包括：

• 用户登录

• 首页数据获取

• 图片加载

• WebSocket 长连接

在 Android 环境下运行正常，但迁移到 OpenHarmony 后，出现以下几个典型问题：

问题	表现
网络请求超时	页面长时间 loading
HTTPS 请求失败	DioException
SocketException	请求直接中断
图片资源无法加载	网络图片白屏

经过排查，发现问题主要集中在：

• OpenHarmony 网络权限

• HTTPS 证书校验

• dio 默认超时配置

• 异常处理机制不完善

因此需要针对鸿蒙平台进行适配优化。

---

二、dio 基础配置

首先创建统一的网络请求封装。

1. 初始化 Dio

class HttpManager {
  static final HttpManager _instance = HttpManager._internal();

  factory HttpManager() {
    return _instance;
  }

  late Dio dio;

  HttpManager._internal() {
    BaseOptions options = BaseOptions(
      baseUrl: "https://api.test.com",
      connectTimeout: const Duration(seconds: 10),
      receiveTimeout: const Duration(seconds: 10),
      sendTimeout: const Duration(seconds: 10),
    );

    dio = Dio(options);

    dio.interceptors.add(
      LogInterceptor(
        requestBody: true,
        responseBody: true,
      ),
    );
  }
}

这里重点配置：

• connectTimeout

• receiveTimeout

• sendTimeout

在 OpenHarmony 中，如果超时时间过短，部分设备容易出现连接失败。

---

三、OpenHarmony 网络权限配置

网络请求失败的第一个排查点，就是应用是否具备网络权限。

在 OpenHarmony 项目中，需要确认配置：

{
  "requestPermissions": [
    {
      "name": "ohos.permission.INTERNET"
    }
  ]
}

如果没有添加该权限，即使代码没有问题，也无法正常访问网络。

这个问题在初次适配时非常容易忽略。

---

四、HTTPS 请求异常处理

1. 常见问题

在鸿蒙设备上，部分 HTTPS 接口会报错：

HandshakeException

或者：

CERTIFICATE_VERIFY_FAILED

主要原因：

• 测试环境证书不规范

• 自签名证书

• 部分接口 TLS 配置不兼容

---

2. 临时解决方案

开发环境下，可以通过 HttpClient 忽略证书校验。

import 'dart:io';

class MyHttpOverrides extends HttpOverrides {
  @override
  HttpClient createHttpClient(SecurityContext? context) {
    return super.createHttpClient(context)
      ..badCertificateCallback =
          (X509Certificate cert, String host, int port) => true;
  }
}

初始化：

void main() {
  HttpOverrides.global = MyHttpOverrides();
  runApp(const MyApp());
}

需要注意：

该方案仅适用于开发调试环境，生产环境不建议关闭证书校验。

---

五、统一异常处理机制

在实际项目中，不能直接把 DioException 暴露给用户。

因此需要建立统一异常处理机制。

1. 创建异常处理类

class ExceptionHandle {
  static String handleException(dynamic error) {
    if (error is DioException) {
      switch (error.type) {
        case DioExceptionType.connectionTimeout:
          return "网络连接超时";

        case DioExceptionType.receiveTimeout:
          return "服务器响应超时";

        case DioExceptionType.badResponse:
          return "服务器异常";

        case DioExceptionType.cancel:
          return "请求已取消";

        default:
          return "网络请求失败";
      }
    }

    return "未知异常";
  }
}

---

2. 请求封装

Future request(
  String path, {
  String method = "GET",
  Map<String, dynamic>? params,
}) async {
  try {
    Response response;

    if (method == "GET") {
      response = await dio.get(path, queryParameters: params);
    } else {
      response = await dio.post(path, data: params);
    }

    return response.data;
  } catch (e) {
    String msg = ExceptionHandle.handleException(e);

    print(msg);

    rethrow;
  }
}

这样能够避免大量重复 try-catch。

---

六、网络重试机制

OpenHarmony 设备在弱网环境下，偶尔会出现请求失败。

为了提高稳定性，可以增加自动重试。

1. 添加 retry 插件

dependencies:
  dio: ^5.0.0
  dio_smart_retry: ^6.0.0

---

2. 配置重试策略

dio.interceptors.add(
  RetryInterceptor(
    dio: dio,
    retries: 3,
    retryDelays: const [
      Duration(seconds: 1),
      Duration(seconds: 2),
      Duration(seconds: 3),
    ],
  ),
);

经过测试后发现：

在网络波动场景下，请求成功率明显提高。

---

七、图片加载异常处理

部分 OpenHarmony 设备中：

Image.network()

可能会出现图片白屏。

解决方案：

CachedNetworkImage(
  imageUrl: imageUrl,
  placeholder: (context, url) =>
      const CircularProgressIndicator(),
  errorWidget: (context, url, error) =>
      const Icon(Icons.error),
)

相比默认 Image.network：

• 稳定性更高

• 支持缓存

• 支持失败占位图

---

八、性能优化实践

在持续请求接口过程中，我发现：

如果频繁创建 Dio 对象，会增加资源消耗。

因此建议：

• 全局单例 Dio

• 统一 Header 管理

• Token 自动注入

• 接口统一日志输出

例如：

dio.options.headers = {
  "token": token,
  "platform": "openharmony"
};

这样后续维护会更加方便。

---

九、实际运行效果

经过适配优化后：

优化项	优化前	优化后
请求成功率	较低	稳定
HTTPS 异常	高频出现	基本解决
超时问题	偶发	明显减少
图片加载	偶发白屏	正常

在鸿蒙真机上连续运行测试后，网络请求已经能够稳定工作。

---

十、总结

本文主要介绍了 Flutter dio 在 OpenHarmony 平台中的网络适配实践，包括：

• 网络权限配置

• HTTPS 异常处理

• Dio 超时设置

• 统一异常处理

• 自动重试机制

• 图片加载优化

在实际开发过程中，Flutter 跨平台虽然能减少大量开发成本，但不同平台之间依然存在细节差异。

因此建议在 OpenHarmony 项目开发时：

• 提前进行真机测试

• 做好异常兜底

• 建立统一网络层

• 避免平台相关问题扩散

后续我也会继续尝试 Flutter 在 OpenHarmony 平台中的更多实践，例如：

• WebSocket 长连接

• MethodChannel 通信

• Flutter 插件适配

• 状态管理优化

希望本文能够对正在进行鸿蒙适配的开发者有所帮助。