Flutter在鸿蒙平台的网络请求配置与Dio实践

1. 项目概述

最近在尝试将Flutter应用集成到开源鸿蒙（HarmonyOS）平台时，遇到了网络请求配置的一系列问题。作为一个跨平台开发的老手，我决定把整个踩坑过程记录下来，特别是那些官方文档没有明确说明的细节。本文将详细介绍如何在鸿蒙平台上为Flutter项目配置网络请求能力，使用Dio库进行HTTP通信，以及如何正确提交代码到Git仓库。

这个方案特别适合以下开发者：

• 已经熟悉Flutter开发，想尝试鸿蒙平台的开发者
• 需要在鸿蒙设备上实现网络功能的Flutter应用开发者
• 对跨平台开发中网络权限配置有困惑的工程师

2. 环境准备与基础配置

2.1 创建Flutter项目

首先，我们需要创建一个标准的Flutter项目作为基础。在命令行中执行：

bash复制flutter create flutter_harmony_demo

这个命令会生成一个基础的Flutter项目结构。值得注意的是，如果你计划将项目同时运行在Android、iOS和HarmonyOS平台上，建议在创建项目时就明确目录结构。我个人习惯使用以下结构：

code复制flutter_harmony_demo/
├── android/       # Android平台代码
├── ios/           # iOS平台代码
├── harmony/       # HarmonyOS平台代码
└── lib/           # 共享的Dart代码

提示：在Windows系统上，路径分隔符要使用反斜杠()，而在macOS/Linux上使用正斜杠(/)。跨平台开发时需要注意这个细节。

2.2 配置Dio网络库

Flutter中最常用的网络请求库是Dio，它比原生http库功能更强大，支持拦截器、全局配置等特性。在pubspec.yaml中添加依赖：

yaml复制dependencies:
  dio: ^5.4.3+1

这里有几个关键点需要注意：

1. 缩进必须严格使用两个空格，不能使用Tab
2. 版本号前的^符号表示允许自动升级到不破坏API兼容性的新版本
3. 修改后需要运行flutter pub get获取依赖

3. 鸿蒙平台网络权限配置

3.1 权限声明配置

鸿蒙平台对权限管理非常严格，要使用网络功能必须显式声明权限。在module.json5文件中添加以下配置：

json复制"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET",
    "reason": "需要网络权限获取任务数据",
    "usedScene": {
      "ability": [".EntryAbility"],
      "when": "inuse"
    }
  }
]

常见错误及解决方法：

1. JSON格式错误：方括号后必须加逗号，否则会报错
2. 权限声明不全：如果还需要其他权限如GPS等，需要一并声明
3. reason字段不能为空：必须说明权限的使用目的

3.2 权限申请时机

在鸿蒙应用中，权限可以在以下时机申请：

1. 应用安装时（不建议，会影响安装转化率）
2. 首次使用功能时（推荐方式）
3. 设置页面中手动触发

最佳实践是在首次需要使用网络功能时动态申请权限，代码如下：

dart复制import 'package:permission_handler/permission_handler.dart';

void requestNetworkPermission() async {
  var status = await Permission.phone.request();
  if (status.isGranted) {
    // 权限已授予
  } else {
    // 处理拒绝情况
  }
}

4. 网络请求实现与调试

4.1 Dio基础配置

建议创建一个单独的Dio管理类，而不是在每个页面都新建实例：

dart复制class HttpUtil {
  static final HttpUtil _instance = HttpUtil._internal();
  factory HttpUtil() => _instance;
  
  late Dio dio;
  
  HttpUtil._internal() {
    dio = Dio(BaseOptions(
      baseUrl: "https://jsonplaceholder.typicode.com",
      connectTimeout: 5000,
      receiveTimeout: 3000,
    ));
    
    // 添加拦截器
    dio.interceptors.add(LogInterceptor(
      request: true,
      requestHeader: true,
      responseBody: true,
    ));
  }
}

4.2 接口调试技巧

在调试接口时，我推荐使用以下工具链：

1. Postman：用于接口调试和文档生成
2. Charles：网络抓包工具，查看实际请求和响应
3. Logger：Flutter的日志打印库，比print更强大

常见问题排查：

1. 接口返回404：检查baseUrl和path是否正确拼接
2. 连接超时：检查设备网络是否正常，是否有代理设置
3. 证书错误：在测试环境可以临时关闭证书验证（生产环境严禁这样做）

dart复制// 临时关闭证书验证（仅用于开发测试）
(dio.httpClientAdapter as DefaultHttpClientAdapter).onHttpClientCreate = 
  (client) {
    client.badCertificateCallback = 
      (X509Certificate cert, String host, int port) => true;
    return client;
  };

5. 代码版本管理

5.1 Git基础配置

建议在项目根目录初始化Git仓库：

bash复制git init
git add .
git commit -m "初始提交"

对于鸿蒙跨平台项目，建议在.gitignore中添加以下内容：

code复制# Flutter相关
/flutter_harmony_demo/.dart_tool/
/flutter_harmony_demo/.pub-cache/
/flutter_harmony_demo/build/

# HarmonyOS相关
/harmony/.gradle/
/harmony/build/
/harmony/.idea/

5.2 两种代码提交方式对比

命令行方式：

bash复制git add .
git commit -m "完成Flutter+鸿蒙列表展示：dio网络请求+鸿蒙权限配置"
git remote add origin https://atomgit.com/yourname/repo.git
git push -u origin master

IDE可视化操作：

1. 在Android Studio/VSCode中打开项目
2. 右键点击项目 → Git → Commit
3. 填写提交信息后点击提交并推送

经验分享：在团队协作中，建议统一使用命令行方式，可以编写脚本自动化流程。而个人小项目使用IDE操作更直观方便。

6. 常见问题与解决方案

6.1 网络权限配置无效

症状：已经配置了权限但依然无法访问网络
可能原因：

1. 配置文件位置错误：必须在entry/src/main/module.json5
2. 权限名称拼写错误：应该是ohos.permission.INTERNET
3. 没有重新编译安装应用

解决方案：

1. 检查配置文件路径
2. 确认权限名称拼写
3. 清理构建后重新运行

6.2 Dio请求抛出异常

常见异常类型：

1. DioErrorType.connectTimeout：连接超时
2. DioErrorType.response：服务器返回错误状态码
3. DioErrorType.cancel：请求被取消

错误处理最佳实践：

dart复制try {
  var response = await dio.get("/todos");
  // 处理正常响应
} on DioError catch (e) {
  if (e.type == DioErrorType.connectTimeout) {
    // 处理超时
  } else if (e.type == DioErrorType.response) {
    // 处理服务器错误
  }
  // 其他错误类型
}

6.3 鸿蒙平台特有问题

1. 真机调试时网络不可用：

   • 检查设备开发者选项是否开启
   • 确认USB调试权限已授权
   • 尝试重启设备和IDE

2. 模拟器网络延迟高：

   • 使用真机调试更可靠
   • 或者调整模拟器网络设置

3. 混合开发时包冲突：

   • 检查Flutter和鸿蒙原生部分的依赖是否冲突
   • 使用dependency_overrides解决版本冲突

7. 性能优化建议

7.1 网络请求优化

1. 合理设置超时时间：

   dart复制BaseOptions(
     connectTimeout: 5000,  // 连接超时5秒
     receiveTimeout: 3000,  // 接收超时3秒
   )
   

2. 使用连接池：

   dart复制dio.httpClientAdapter = DefaultHttpClientAdapter()
     ..maxConnectionsPerHost = 5;
   

3. 缓存策略：

   • 对静态数据使用内存缓存
   • 对频繁访问的数据使用磁盘缓存

7.2 鸿蒙平台优化

1. 减少跨平台通信：

   • 尽量在Dart层完成业务逻辑
   • 避免频繁调用原生平台代码

2. 资源优化：

   • 使用鸿蒙提供的资源管理机制
   • 按需加载资源文件

3. 线程管理：

   • 网络请求默认在IO线程执行
   • UI更新必须在主线程

8. 项目结构建议

对于长期维护的跨平台项目，我推荐以下结构：

code复制flutter_harmony_demo/
├── assets/               # 静态资源
├── lib/
│   ├── api/              # 网络请求相关
│   │   ├── http_util.dart
│   │   └── api.dart
│   ├── models/           # 数据模型
│   ├── pages/            # 页面
│   ├── utils/            # 工具类
│   └── main.dart
├── harmony/              # 鸿蒙平台代码
├── android/              # Android平台代码
└── ios/                  # iOS平台代码

这种结构的好处是：

1. 关注点分离，便于维护
2. 各平台代码互不干扰
3. 共享代码集中管理

9. 持续集成建议

对于团队项目，建议设置CI/CD流程：

1. 代码提交触发自动构建
2. 运行单元测试和集成测试
3. 静态代码分析
4. 自动打包部署

示例GitLab CI配置：

yaml复制stages:
  - test
  - build

flutter_test:
  stage: test
  script:
    - flutter pub get
    - flutter test

harmony_build:
  stage: build
  script:
    - cd harmony
    - ./gradlew assembleRelease

10. 扩展思考

这个项目虽然完成了基础功能，但还有不少可以优化的地方：

1. 安全性增强：

   • 添加HTTPS证书固定
   • 实现请求签名
   • 敏感数据加密

2. 用户体验提升：

   • 添加加载状态指示
   • 实现离线缓存
   • 错误页面友好提示

3. 架构优化：

   • 引入状态管理（如Provider或Bloc）
   • 实现依赖注入
   • 组件化拆分

在实际开发中，我通常会先实现核心功能，再逐步迭代优化。特别是在跨平台开发中，要时刻考虑各平台的特性差异，找到最佳的平衡点。