Flutter+OpenHarmony电子合同下载功能开发实践

1. 项目背景与需求分析

在移动应用开发领域，电子合同签署正成为企业数字化转型的关键环节。作为一名长期从事跨平台开发的工程师，我最近接到一个需求：为OpenHarmony生态开发一款电子合同签署App，其中合同下载功能是核心模块之一。这个需求看似简单，但在Flutter+OpenHarmony的技术栈组合下却有不少值得探讨的技术细节。

为什么选择Flutter+OpenHarmony？Flutter的跨平台能力可以让我们用一套代码覆盖多个设备形态，而OpenHarmony作为新兴操作系统，其分布式能力非常适合电子合同这类需要多端协同的场景。合同下载功能看似基础，实则涉及网络请求、文件存储、权限管理等多个技术点，特别是在OpenHarmony环境下还需要考虑系统特性适配。

2. 环境准备与项目搭建

2.1 Flutter for OpenHarmony环境配置

要在OpenHarmony上运行Flutter应用，首先需要搭建特殊的环境：

bash复制# 安装Flutter SDK
git clone https://github.com/flutter/flutter.git -b stable
export PATH="$PATH:`pwd`/flutter/bin"

# 安装OpenHarmony工具链
npm install -g @ohos/hpm-cli
hpm install @ohos/llvm @ohos/ninja

注意：目前Flutter对OpenHarmony的支持还在完善中，建议使用Flutter 3.7+版本以获得最佳兼容性。

2.2 项目初始化

创建一个新的Flutter项目并添加OpenHarmony支持：

bash复制flutter create --platforms=ohos contract_signing_app
cd contract_signing_app
flutter pub add dio path_provider_ohos

这里我们使用了dio作为网络请求库，path_provider_ohos是专门为OpenHarmony适配的文件路径获取插件。

3. 合同下载功能实现

3.1 网络请求与文件下载

电子合同通常以PDF格式提供，我们需要从服务器下载合同文件。以下是核心实现代码：

dart复制import 'package:dio/dio.dart';
import 'package:path_provider_ohos/path_provider_ohos.dart';

Future<String> downloadContract(String url, String fileName) async {
  // 获取应用文档目录
  final dir = await getApplicationDocumentsDirectory();
  final savePath = '${dir.path}/$fileName.pdf';
  
  try {
    final response = await Dio().download(
      url,
      savePath,
      onReceiveProgress: (received, total) {
        if (total != -1) {
          print('${(received / total * 100).toStringAsFixed(0)}%');
        }
      },
    );
    return savePath;
  } catch (e) {
    print('下载失败: $e');
    throw Exception('合同下载失败');
  }
}

这段代码实现了：

1. 使用dio库的download方法下载文件
2. 通过path_provider_ohos获取OpenHarmony上的合法存储路径
3. 添加了下载进度回调
4. 进行了基本的错误处理

3.2 OpenHarmony文件系统适配

OpenHarmony的文件系统与Android/iOS有显著差异，需要特别注意：

1. 存储权限：虽然Flutter应用默认有内部存储权限，但如果要访问共享存储空间，需要在config.json中添加权限声明：

json复制{
  "module": {
    "reqPermissions": [
      {
        "name": "ohos.permission.READ_MEDIA",
        "reason": "用于存储下载的合同文件"
      },
      {
        "name": "ohos.permission.WRITE_MEDIA",
        "reason": "用于存储下载的合同文件"
      }
    ]
  }
}

2. 文件路径处理：OpenHarmony使用类似Linux的文件系统结构，应用私有目录通常位于/data/app/el1/bundle/public/[包名]下。通过path_provider_ohos插件可以屏蔽这些细节。

4. 下载管理优化

4.1 断点续传实现

对于大文件合同，断点续传是必备功能。我们可以利用dio的Options.extra实现：

dart复制Future<String> downloadWithResume(String url, String fileName) async {
  final dir = await getApplicationDocumentsDirectory();
  final savePath = '${dir.path}/$fileName.pdf';
  final tempPath = '$savePath.temp';
  
  // 检查已有下载进度
  int received = await _getReceivedLength(tempPath);
  
  return await Dio().download(
    url,
    tempPath,
    options: Options(
      extra: {
        'withProgress': true,
        'receiveDataWhenError': true,
      },
      headers: received > 0 
          ? {'range': 'bytes=$received-'} 
          : {},
    ),
    onReceiveProgress: (received, total) {
      // 更新进度
    },
  ).then((_) {
    // 下载完成后重命名文件
    return File(tempPath).rename(savePath).then((_) => savePath);
  });
}

Future<int> _getReceivedLength(String path) async {
  try {
    final file = File(path);
    return await file.exists() ? await file.length() : 0;
  } catch (_) {
    return 0;
  }
}

4.2 下载队列管理

当用户需要批量下载多份合同时，合理的队列管理可以避免资源竞争：

dart复制class DownloadQueue {
  final Dio _dio = Dio();
  final List<DownloadTask> _queue = [];
  final int _maxConcurrent = 2;
  int _activeCount = 0;

  Future<void> addTask(DownloadTask task) async {
    _queue.add(task);
    _processQueue();
  }

  void _processQueue() {
    while (_activeCount < _maxConcurrent && _queue.isNotEmpty) {
      _activeCount++;
      final task = _queue.removeAt(0);
      _executeTask(task).whenComplete(() {
        _activeCount--;
        _processQueue();
      });
    }
  }

  Future<void> _executeTask(DownloadTask task) async {
    try {
      await _dio.download(
        task.url,
        task.savePath,
        onReceiveProgress: task.onProgress,
      );
      task.completer.complete(task.savePath);
    } catch (e) {
      task.completer.completeError(e);
    }
  }
}

class DownloadTask {
  final String url;
  final String savePath;
  final void Function(int, int)? onProgress;
  final Completer<String> completer = Completer();
  
  DownloadTask(this.url, this.savePath, [this.onProgress]);
}

5. 安全与性能优化

5.1 文件完整性校验

下载后的合同文件需要验证完整性，通常使用MD5校验：

dart复制import 'package:crypto/crypto.dart';
import 'dart:io';
import 'dart:convert';

Future<bool> verifyFile(String path, String expectedMd5) async {
  final file = File(path);
  if (!await file.exists()) return false;
  
  final bytes = await file.readAsBytes();
  final digest = md5.convert(bytes);
  return digest.toString() == expectedMd5;
}

5.2 加密存储

对于敏感合同文件，建议加密存储：

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

Future<void> encryptFile(String inputPath, String outputPath, String key) async {
  final encrypter = Encryptor(AES(Key.fromUtf8(key)));
  final input = File(inputPath);
  final output = File(outputPath);
  
  final bytes = await input.readAsBytes();
  final encrypted = encrypter.encryptBytes(bytes);
  await output.writeAsBytes(encrypted.bytes);
}

6. OpenHarmony特性适配

6.1 分布式文件访问

利用OpenHarmony的分布式能力，可以实现跨设备文件访问：

dart复制import 'package:ohos_distributed_file/distributed_file.dart';

Future<void> shareToOtherDevice(String filePath) async {
  final distributedFile = DistributedFile();
  final result = await distributedFile.share(
    filePath: filePath,
    targetDevice: 'any', // 或指定设备ID
  );
  if (!result) {
    throw Exception('分布式分享失败');
  }
}

6.2 系统通知集成

下载完成后触发系统通知：

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

Future<void> showDownloadCompleteNotification(String fileName) async {
  final notification = Notification(
    id: 1,
    title: '合同下载完成',
    content: '$fileName 已下载完成',
    smallIcon: ResourceTable.Media_icon,
  );
  await OhosNotification().show(notification);
}

7. 测试与调试

7.1 单元测试

为下载功能编写单元测试：

dart复制void main() {
  test('测试合同下载', () async {
    // 使用mock server
    final server = await HttpServer.bind('localhost', 0);
    server.listen((request) {
      request.response
        ..headers.contentType = ContentType.binary
        ..add(List.filled(1024, 0)) // 1KB测试文件
        ..close();
    });
    
    final url = 'http://localhost:${server.port}/test.pdf';
    final path = await downloadContract(url, 'test');
    
    expect(File(path).existsSync(), isTrue);
    await server.close();
  });
}

7.2 真机调试技巧

在OpenHarmony真机调试时，可以通过以下命令获取日志：

bash复制# 查看Flutter日志
flutter logs

# 查看OpenHarmony系统日志
hdc shell hilog | grep flutter

8. 性能优化实践

8.1 内存优化

大文件下载时容易引发OOM，可以通过流式处理优化：

dart复制Future<String> streamDownload(String url, String fileName) async {
  final dir = await getApplicationDocumentsDirectory();
  final savePath = '${dir.path}/$fileName.pdf';
  final file = File(savePath);
  final sink = file.openWrite();
  
  try {
    final response = await Dio().get(
      url,
      options: Options(responseType: ResponseType.stream),
    );
    
    final stream = response.data as ResponseBody;
    await stream.stream.pipe(sink);
    return savePath;
  } finally {
    await sink.close();
  }
}

8.2 后台下载

实现后台下载服务：

dart复制// 在main.dart中注册后台回调
void downloaderBackgroundCallback() {
  WidgetsFlutterBinding.ensureInitialized();
  const MethodChannel('downloader').setMethodCallHandler((call) async {
    if (call.method == 'download') {
      final url = call.arguments['url'];
      final file = call.arguments['file'];
      await downloadContract(url, file);
    }
  });
}

// 在OpenHarmony的Service中调用
const channel = MethodChannel('downloader');
await channel.invokeMethod('download', {
  'url': 'https://example.com/contract.pdf',
  'file': 'important_contract',
});

9. 实际开发中的经验总结

在完成这个电子合同下载功能的过程中，我积累了一些宝贵经验：

1. 路径处理：OpenHarmony的文件路径规则与Android不同，直接使用硬编码路径会导致问题，必须通过path_provider_ohos等插件获取合法路径。

2. 权限时机：OpenHarmony的运行时权限弹窗时机与Android不同，建议在应用启动时就申请必要的存储权限。

3. 网络适配：部分OpenHarmony设备可能使用非标准网络栈，遇到网络问题时可以尝试在config.json中添加网络权限：

json复制{
  "module": {
    "reqPermissions": [
      {
        "name": "ohos.permission.GET_NETWORK_INFO"
      },
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

4. 文件系统观察：OpenHarmony的文件系统通知机制与Android的FileObserver不同，可以使用ohos_file_observer插件来监听文件变化。

5. 性能监控：在下载大文件时，建议定期检查内存使用情况，避免被系统终止：

dart复制void _checkMemoryUsage() {
  final usage = MemoryUsage.current();
  if (usage.usedInBytes > usage.thresholdInBytes * 0.8) {
    print('内存使用过高，当前使用率: ${usage.usedPercent.toStringAsFixed(1)}%');
    // 释放资源或暂停部分下载
  }
}

这个电子合同下载功能的实现过程让我深刻体会到，在OpenHarmony上开发Flutter应用既需要掌握Flutter的跨平台特性，又需要了解OpenHarmony的系统特性。特别是在文件系统和网络访问这些与平台强相关的功能上，合理的架构设计和充分的测试是保证功能稳定性的关键。