鸿蒙系统适配dart_mongo_lite的实践与优化

1. 为什么需要鸿蒙化适配dart_mongo_lite

在Flutter生态中，dart_mongo_lite作为轻量级MongoDB客户端库，原本设计用于Android/iOS平台的文档数据库操作。但当开发者尝试在鸿蒙系统上运行时，会遇到三个典型问题：

1. 网络权限配置差异：鸿蒙的config.json权限声明方式与Android的AndroidManifest.xml完全不同，导致基础网络请求都无法发出
2. 线程模型冲突：鸿蒙的Worker线程机制与Dart的Isolate存在兼容性问题，批量插入数据时频繁崩溃
3. 平台通道异常：MethodChannel在鸿蒙上返回的数据类型会被自动包装成OHOS特有格式，导致BSON解析失败

去年我们在电商App项目中就遭遇过这种困境——当华为逐步将设备升级为鸿蒙系统后，原本运行良好的商品收藏同步功能突然大面积失效。通过抓包分析发现，所有MongoDB操作请求甚至没能离开设备端。

关键发现：鸿蒙系统对Socket连接有特殊的保活机制，默认30秒无数据传输会强制断开。而dart_mongo_lite原生版本的心跳间隔是45秒，这直接导致了长连接稳定性问题。

2. 环境准备与依赖调整

2.1 鸿蒙开发环境特殊配置

首先在build.gradle中需要增加鸿蒙的maven仓库配置：

groovy复制repositories {
    maven {
        url 'https://repo.harmonyos.com/nexus/content/groups/public/'
    }
}

然后在ohos目录下的config.json中添加网络权限（这是与Android最大的不同点）：

json复制{
  "module": {
    "reqPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "MongoDB connection"
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO",
        "reason": "Monitor network state"
      }
    ]
  }
}

2.2 修改pubspec.yaml依赖

原版dart_mongo_lite需要替换为我们的适配分支：

yaml复制dependencies:
  dart_mongo_lite:
    git:
      url: https://gitee.com/harmony-fork/dart_mongo_lite.git
      ref: harmony-3.0

同时增加鸿蒙平台特定的dart代码隔离：

yaml复制flutter:
  plugin:
    platforms:
      harmonyos:
        package_name: com.example.mongo_lite
        plugin_class: MongoLitePlugin

3. 核心代码适配方案

3.1 网络连接层改造

鸿蒙的http客户端实现需要替换默认的dart:io网络栈。在lib/src/network下新建harmony_connection.dart：

dart复制class HarmonyConnection implements MongoConnection {
  final HttpClient _httpClient = HttpClient()
    ..connectionTimeout = Duration(seconds: 10)
    ..idleTimeout = Duration(seconds: 25); // 必须小于30秒鸿蒙限制
  
  @override
  Future<MongoResponse> sendRequest(MongoRequest request) async {
    final uri = Uri.parse('${request.endpoint}/command');
    final httpRequest = await _httpClient.postUrl(uri);
    httpRequest.headers.add('Content-Type', 'application/bson');
    
    // 鸿蒙系统要求显式设置Content-Length
    final bsonData = request.toBson();
    httpRequest.contentLength = bsonData.length;
    httpRequest.add(bsonData);
    
    final response = await httpRequest.close();
    if (response.statusCode != 200) {
      throw MongoNetworkError('HTTP ${response.statusCode}');
    }
    
    final data = await consolidateHttpClientResponseBytes(response);
    return MongoResponse.fromBson(data);
  }
}

3.2 线程安全处理

鸿蒙的UI线程与Worker线程交互需要特殊处理。修改lib/src/executor.dart中的查询执行器：

dart复制class HarmonyExecutor extends MongoExecutor {
  static final _isolatePort = ReceivePort();
  
  @override
  void initialize() {
    // 鸿蒙需要显式注册Dart层监听器
    BackgroundTaskManager.registerBackgroundTaskHandler((taskData) {
      _isolatePort.send(taskData);
    });
  }

  @override
  Future<MongoCursor> executeQuery(MongoQuery query) async {
    if (Platform.isHarmonyOS) {
      // 将查询任务分发到Worker线程
      final completer = Completer<MongoCursor>();
      final sendPort = _isolatePort.sendPort;
      sendPort.send({
        'type': 'query',
        'query': query.serialize(),
        'replyTo': completer.complete
      });
      return completer.future;
    }
    return super.executeQuery(query);
  }
}

4. 典型问题排查指南

4.1 连接超时问题

现象：控制台报错SocketException: Connection timed out (OS Error: 110)

解决方案分三步走：

1. 检查config.json权限声明是否完整
2. 确认网络心跳间隔已调整为25秒以内
3. 在鸿蒙设备上执行：

bash复制hicheck list | grep NETWORK

查看网络策略是否被系统限制

4.2 BSON解析异常

当遇到InvalidBSON: unexpected end of byte stream错误时：

1. 在鸿蒙端添加数据转换层：

dart复制BsonBinary harmonizeBson(List<int> raw) {
  // 鸿蒙返回的数据会多出4字节头信息
  if (raw.length > 4 && raw[0] == 0x01 && raw[1] == 0x02) {
    return BsonBinary.from(raw.sublist(4));
  }
  return BsonBinary.from(raw);
}

2. 修改MongoResponse解析逻辑：

dart复制MongoResponse.fromBson(List<int> data) {
  try {
    return MongoResponse._fromBson(harmonizeBson(data));
  } catch (e) {
    // 原始格式回退
    return MongoResponse._fromBson(BsonBinary.from(data));
  }
}

5. 性能优化实践

在智能家居控制App的实际测试中，我们总结出三点鸿蒙专属优化技巧：

1. 批量操作分片：鸿蒙的Worker线程内存限制更严格，建议将批量插入拆分为每批50条记录

dart复制Future<void> bulkInsert(List<Map<String,dynamic>> docs) async {
  const chunkSize = 50;
  for (var i = 0; i < docs.length; i += chunkSize) {
    final chunk = docs.sublist(i, min(i + chunkSize, docs.length));
    await collection.insertMany(chunk);
  }
}

2. 连接池预热：鸿蒙首次建立Socket连接耗时较长，应用启动时应预先建立2-3个连接

dart复制void prewarmConnections() {
  for (var i = 0; i < 3; i++) {
    _connectionPool.add(ConnectionFactory.create());
  }
}

3. 查询结果缓存：利用鸿蒙的Preferences能力缓存高频查询

dart复制Future<List<Map>> getCachedQuery(String key, MongoQuery query) async {
  final prefs = await Preferences.getInstance();
  if (prefs.contains(key)) {
    return json.decode(prefs.getString(key));
  }
  
  final result = await executeQuery(query);
  prefs.putString(key, json.encode(result));
  return result;
}

在华为MatePad Pro上测试，优化后的查询延迟从原来的1200ms降低到400ms左右。内存占用峰值下降约35%，这对鸿蒙的轻量化设备尤为重要。