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

Flutter 三方库 mysql1 的鸿蒙化适配指南 - 实现移动端直接访问 MySQL 数据库、支持高性能连接池、赋能鸿蒙应用后端管理与数据直连方案

前言

在大多数移动应用场景中，我们通过 RESTful API 或 GraphQL 来获取数据。但在某些特定的企业内部工具、简单的后台管理系统或特定物联网（IoT）监控场景下，移动端需要直接访问 MySQL 数据库。mysql1 是 Dart 社区中广泛使用的异步 MySQL 驱动库。本文将带你实战如何在 Flutter for OpenHarmony（鸿蒙）项目中适配并稳定运行 mysql1，实现端云直连的数据交互能力。

一、原原理析 / 概念介绍

1.1 基础原理/概念介绍

mysql1 是一个基于 Dart socket 实现的纯驱动程序，它支持 MySQL 的二进制协议（Binary Protocol），能够实现高效的 SQL 执行、结果集解析以及事务处理。

1.2 为什么在鸿蒙项目中使用它？

1. 开发效率极高：无需编写中间层接口，直接在 Flutter 代码中操作 SQL。
2. 轻量级连接池：支持物理连接复用，降低鸿蒙端频繁创建连接的开销。
3. 支持事务：确保鸿蒙应用在处理敏感财务数据时的原子性。

指标	传统 API 模式	mysql1 直连模式
架构复杂度	高（三层架构）	低（双层架构）
开发速度	中	极快
适用场景	公网大规模应用	企业内网、工具类应用

二、鸿蒙基础指导

2.1 适配情况

1. 是否原生支持？：是，底层依赖 Dart Socket，不含任何 C++ 原生代码。
2. 是否鸿蒙官方支持？：社区驱动支持。
3. 适配注意：必须在鸿蒙 module.json5 中声明 ohos.permission.INTERNET 权限，否则无法建立 TCP 连接。

2.2 核心连接配置

在鸿蒙环境中，通常需要配置连接选项以应对移动网络的不稳定性。

import 'package:mysql1/mysql1.dart';

Future<MySqlConnection> connectToHarmonyDb() async {
  final settings = ConnectionSettings(
    host: 'db.example.com',
    port: 3306,
    user: 'harmony_user',
    password: 'secure_password',
    db: 'harmony_data',
    // 增加超时设置适配弱网环境
    timeout: const Duration(seconds: 30),
  );
  
  return await MySqlConnection.connect(settings);
}

三、核心 API / 组件详解

3.1 执行 SQL 查询

通过适配后的 mysql1 获取鸿蒙系统状态表数据。

3.2 事务处理

针对金融或库存类应用，确保数据的强一致性。

await conn.transaction((ctx) async {
  await ctx.query('update wallet set balance = balance - 100 where id = ?', [1]);
  await ctx.query('insert into trnasaction_log (amount) values (?)', [100]);
});

四、典型应用场景

4.1 场景一：企业内部资产巡检系统

外勤人员使用鸿蒙平板进行资产扫描，数据直接实时写入后台数据库。

// 汉化示例：记录设巡检状态
Future<void> logAssetCheck(int assetId, String status) async {
  var conn = await MySqlConnection.connect(settings);
  await conn.query(
    'INSERT INTO 巡检记录 (资产ID, 状态, 巡检时间) VALUES (?, ?, NOW())', 
    [assetId, status]
  );
  await conn.close();
}

4.2 场景二：物联网监控看板

实时汇总多台鸿蒙嵌入式设备采集的传感器数据。

// 批量插入传感器读数
var results = await conn.queryMulti(
  'INSERT INTO 传感器数据 (温度, 湿度) VALUES (?, ?)',
  [[25.5, 60], [26.0, 58], [24.8, 62]]
);

五、OpenHarmony 平台适配挑战

5.1 网络切换导致的 Socket 挂起

当鸿蒙设备从 Wi-Fi 切换到 5G 网络时，底层的 TCP Socket 连接往往会丢失。
解决方案：建议实现一个心跳包逻辑或使用 pool（连接池）库。在执行查询前检查连接活性，如果失效则自动触发重连。

5.2 数据库连接安全（核心挑战）

直接暴露数据库端口在公网是不安全的。
解决方案：在鸿蒙端建议配合 VPN 或 SSH 隧道使用。如果是为了敏捷迭代，务必使用只读用户或具有部分权限的特定数据库用户，严禁直接在鸿蒙端代码中硬编码 root 权限。

六、综合实战演示

import 'package:flutter/material.dart';
import 'package:mysql1/mysql1.dart';

class DatabaseApp extends StatefulWidget {
  @override
  _DatabaseAppState createState() => _DatabaseAppState();
}

class _DatabaseAppState extends State<DatabaseApp> {
  String _status = "等待连接...";

  Future<void> _fetchData() async {
    try {
      final conn = await MySqlConnection.connect(ConnectionSettings(
        host: 'your-host', port: 3306, user: 'user', db: 'db'
      ));
      var results = await conn.query('SELECT count(*) as total FROM users');
      setState(() {
        _status = "数据库中共有用户：${results.first['total']} 人";
      });
      await conn.close();
    } catch (e) {
      setState(() { _status = "连接失败：$e"; });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('鸿蒙端直连 MySQL 实战')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(_status, style: TextStyle(fontSize: 18)),
            SizedBox(height: 20),
            ElevatedButton(onPressed: _fetchData, child: Text("刷新数据"))
          ],
        ),
      ),
    );
  }
}

七、总结

mysql1 库的适配为鸿蒙开发者提供了更灵活的数据访问选择。虽然在大型商用项目中我们依然推荐 API 转发模式，但在特定领域（如敏捷原型、私有化部署、内网管理）中，这种端云直连的能力具有无可比拟的优势。掌握这一技术，将助力在鸿蒙生态中构建更高效、更直接的数据链路。

[!CAUTION]
移动端直连数据库仅限受信任网络使用，生产环境请务必配合多重身份验证及加密隧道。