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

Flutter 三方库 galileo_mysql 的鸿蒙化适配指南 - 支持 MySQL 8.0 协议、高性能长连接与异步事务处理

前言

在 Flutter for OpenHarmony 的应用开发中，直接在端侧进行数据库操作虽然不是主流（通常通过 API），但在某些边缘计算或内网工具类场景下，直接连接 MySQL 数据库依然是刚需。galileo_mysql 作为一个纯 Dart 实现的 MySQL 驱动，其天然的跨平台属性使其成为鸿蒙端直接操作 MySQL 的首选。本文将详细介绍如何在 OpenHarmony 环境下适配并使用该库。

一、原理解析 / 概念介绍

1.1 基础原理

galileo_mysql 是基于 MySQL 客户端/服务器协议的纯 Dart 实现。它通过底层 Socket 与 MySQL Server 进行通信，支持认证、查询、结果解析等核心流程。

1.2 核心优势

• 纯 Dart 实现：不依赖原生 C 库，适配鸿蒙零门槛。
• 支持 MySQL 8.0：兼容最新的认证插件。
• 连接池管理：有效减少频繁建连带来的性能损耗。
• 全异步设计：完美契合 Flutter 的事件循环模式。

二、鸿蒙基础指导

2.1 适配情况

1. 是否原生支持？ 是，基于 Dart 标准库 dart:io。
2. 是否鸿蒙官方支持？ 社区支持。
3. 是否需要安装额外的 package？ 不需要，直接引入即可。

2.2 适配代码

在鸿蒙工程的 pubspec.yaml 中添加依赖：

dependencies:
  galileo_mysql: ^2.1.0

由于是纯 Dart 库，在鸿蒙端无需配置 module.json5 中的特殊原生权限，只需确保应用拥有网络访问权限。

三、核心 API / 组件详解

3.1 快速上手

API	说明
MySqlConnection.connect()	异步建立数据库连接
query()	执行 SQL 查询
execute()	执行非查询 SQL（如 INSERT/UPDATE）
transaction()	开启事务处理

3.2 基础配置

import 'package:galileo_mysql/galileo_mysql.dart';

Future<void> basicConnect() async {
  final settings = ConnectionSettings(
    host: '192.168.1.100', // 数据库地址
    port: 3306,
    user: 'root',
    password: 'password',
    db: 'test_db'
  );

  // 建立连接
  final conn = await MySqlConnection.connect(settings);
  print('鸿蒙端已成功连接至 MySQL！');
  await conn.close();
}

四、典型应用场景

4.1 数据查询

Future<void> queryData() async {
  final conn = await MySqlConnection.connect(settings);
  // 查询用户表
  var results = await conn.query('select name, email from users where id = ?', [1]);
  for (var row in results) {
    print('用户名称: ${row[0]}, 邮箱: ${row[1]}');
  }
  await conn.close();
}

4.2 事务处理

Future<void> runTransaction() async {
  final conn = await MySqlConnection.connect(settings);
  await conn.transaction((ctx) async {
    await ctx.query('update accounts set balance = balance - 100 where id = 1');
    await ctx.query('update accounts set balance = balance + 100 where id = 2');
    print('鸿蒙端转账事务执行成功');
  });
  await conn.close();
}

五、OpenHarmony 平台适配挑战

5.1 网络沙箱限制

鸿蒙系统对网络访问有严格的沙箱管控。在真机调试时，必须在 module.json5 中声明 ohos.permission.INTERNET 权限，否则 Socket 连接会直接被系统拦截。

5.2 字符编码转换

在处理中文数据时，需确保 MySQL Server 编码为 utf8mb4。galileo_mysql 底层会自动处理 Dart 字符串到 UTF-8 的转换，但在复杂的中文字符集环境下，建议显式设置数据库连接校对集。

六、综合实战演示

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

class MySqlDemo extends StatefulWidget {
  @override
  _MySqlDemoState createState() => _MySqlDemoState();
}

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

  Future<void> _testConnection() async {
    try {
      final settings = ConnectionSettings(
        host: 'your_mysql_host',
        user: 'admin',
        password: 'password',
        db: 'demo'
      );
      final conn = await MySqlConnection.connect(settings);
      setState(() {
        _status = "鸿蒙真机连接 MySQL 成功！";
      });
      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),
            ElevatedButton(
              onPressed: _testConnection,
              child: Text('点击测试连接'),
            ),
          ],
        ),
      ),
    );
  }
}

七、总结

galileo_mysql 在 Flutter for OpenHarmony 上的表现非常稳定。由于其纯 Dart 的特性，开发者可以无缝从其他平台迁移数据库逻辑。只要处理好鸿蒙的网络权限和 Socket 连接稳定性，它就能成为你鸿蒙应用中可靠的数据引擎。