Flutter for OpenHarmony 实战：FFI — 调用 C/C++ 代码的桥梁

前言

在高性能计算、底层系统访问（如音频处理、渲染引擎）或复用现有 C/C++ 库的场景下，FFI (Foreign Function Interface) 是 Flutter 开发者必不可少的杀手锏。对于 Flutter for OpenHarmony 而言，FFI 更是连接 Dart 代码与鸿蒙原生 Native 能力的“高速公路”，它避开了传统的 Channel 通信开销，实现了接近原生的执行效率。

本文将带你从深度剖析 FFI 原理开始，手把手教你在鸿蒙项目上集成高性能的 C++ 逻辑。

一、FFI 的核心工作原理

在跨平台开发中，FFI 允许 Dart 虚拟机直接加载共享库（.so 文件），并调用其中的函数。

1.1 零拷贝的优势

传统的 MethodChannel 需要经过二进制序列化、跨线程传输、反序列化等多个阶段。而 FFI 直接在相同的内存地址空间内进行函数指针调用。

• 🚀 极低延迟：适用于每秒数百次调用的频繁交互场景。
• 🚀 内存共享：支持在 Dart 与 C++ 之间直接操作共享的数据缓冲区。

1.2 鸿蒙下的库加载流程

在鸿蒙系统（HarmonyOS NEXT）中，Native 层代码通过 CMake 编译成 .so 文件。Dart 侧利用 DynamicLibrary.open 动态加载该库，并通过函数签名匹配找到对应的符号地址。

---

二、配置环境：鸿蒙项目的 C++ 工程搭建

2.1 修改 CMakeLists.txt

在项目的 ohos/ 目录下，确保你的 C++ 代码能够正确编译为库文件。

# ohos/src/main/cpp/CMakeLists.txt
add_library(native_image_proc SHARED image_processor.cpp)

# 确保链接了必要的系统库
target_link_libraries(native_image_proc hilog_ndk.z)

2.2 引入 Dart 依赖 📦

在 pubspec.yaml 中添加：

dependencies:
  ffi: ^2.1.0

---

三、核心功能：3 个场景化小示例

3.1 简单的数学计算 (Basic)

将 C 层的高性能算法暴露给 Dart 使用。

// C++ 代码
extern "C" __attribute__((visibility("default"))) __attribute__((used))
int32_t native_add(int32_t a, int32_t b) {
    return a + b;
}

// Dart 调用
final DynamicLibrary nativeLib = DynamicLibrary.open('libnative_image_proc.so');
typedef NativeAdd = Int32 Function(Int32, Int32);
typedef DartAdd = int Function(int, int);

final dartAdd = nativeLib.lookupFunction<NativeAdd, DartAdd>('native_add');
print('FFI 计算结果: ${dartAdd(10, 20)}');

3.2 字符串传递 (String Handling)

FFI 中的字符串需要进行内存分配与释放，这是最容易产生空指针的地方。

// ✅ 正确做法：使用 ffi 扩展包进行转换
import 'package:ffi/ffi.dart';

void sendStringToNative(String data) {
  final Pointer<Utf8> charPtr = data.toNativeUtf8();
  try {
    nativePrintFunc(charPtr); // 将指针传给 Native
  } finally {
    malloc.free(charPtr); // ⚠️ 必须手动手动释放内存
  }
}

3.3 异步回调执行 (Native Port)

利用 NativeCallable 实现 C++ 层触发 Dart 函数执行。

// 只有 Dart 3.0+ 支持的高级特性
final callback = NativeCallable<Void Function()>.isolateLocal(() {
  print('来自鸿蒙 Native 层的异步通知');
});
registerCallback(callback.nativeFunction);

---

四、OpenHarmony 平台适配指南

在鸿蒙系统应用 FFI 时，需注意以下关键细节：

4.1 ABI 架构匹配 🏗️

⚠️ 注意：鸿蒙真机（如 Mate 60）主要运行在 arm64-v8a 架构上。

• ✅ 建议：在 hvigor 配置或 CMake 脚本中，务必配置好针对 arm64-v8a 的编译优化，以发挥鸿蒙芯片最大效能。

4.2 符号可见性

鸿蒙系统对 .so 库的导出符号有严格限制。

• 💡 技巧：确保 C 接口使用 extern "C" 包装，并添加 __attribute__((visibility("default")))，否则 Dart 的 lookup 将报错找不到符号。

---

五、完整实战示例：集成 C++ 图像灰度化滤镜

我们将构建一个高性能的实战案例：在 Native 层处理图像像素数据，实现灰度化效果。

import 'dart:ffi';
import 'dart:typed_data';
import 'package:flutter/material.dart';
import 'package:ffi/ffi.dart';

// 1. 定义 C 层的函数签名 (模拟)
typedef NativeGrayScale = Void Function(Pointer<Uint8> data, Int32 length);
typedef DartGrayScale = void Function(Pointer<Uint8> data, int length);

class FfiImageEnginePage extends StatefulWidget {
  const FfiImageEnginePage({super.key});

  @override
  State<FfiImageEnginePage> createState() => _FfiImageEnginePageState();
}

class _FfiImageEnginePageState extends State<FfiImageEnginePage> {
  String _status = "等待处理数据...";

  void _runNativeProcess() {
    // 💡 技巧：在真实鸿蒙项目中，由于是动态加载 .so，这里需要 try-catch 捕获库未找到异常
    try {
      // 模拟加载：DynamicLibrary.open('libnative_image_proc.so');
      setState(() {
        _status = "尝试加载 libnative_image_proc.so...\n(注：此演示仅展示 FFI 定义逻辑)";
      });

      final mockPixels = Uint8List.fromList([255, 128, 64]);

      // 💡 技巧：分配 Native 堆内存
      final Pointer<Uint8> buffer = malloc.allocate<Uint8>(mockPixels.length);
      final pointerList = buffer.asTypedList(mockPixels.length);
      pointerList.setAll(0, mockPixels);

      // ... 逻辑执行 ...

      malloc.free(buffer); // ⚠️ 必须手动释放，防止鸿蒙应用 OOM
    } catch (e) {
      setState(() {
        _status = "FFI 运行演示：需在鸿蒙真机环境部署 .so 库方可完整运行。\n当前已成功构建 C 接口绑定逻辑。";
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('FFI 鸿蒙 Native 桥接')),
      body: Padding(
        padding: const EdgeInsets.all(24.0),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            const Card(
              color: Color(0xFFFFF3E0),
              child: Padding(
                padding: EdgeInsets.all(16.0),
                child: Text(
                    'FFI (Foreign Function Interface) 是连接 Dart 与鸿蒙 C++ 代码的高速公路，避开了 Channel 的序列化开销。',
                    style: TextStyle(color: Colors.orange, fontSize: 13)),
              ),
            ),
            const SizedBox(height: 30),
            const Text('执行状态：', style: TextStyle(fontWeight: FontWeight.bold)),
            const SizedBox(height: 10),
            Text(_status,
                style: const TextStyle(
                    fontFamily: 'monospace', color: Colors.blueGrey)),
            const Spacer(),
            ElevatedButton(
              onPressed: _runNativeProcess,
              style: ElevatedButton.styleFrom(
                backgroundColor: Colors.black87,
                foregroundColor: Colors.white,
                padding: const EdgeInsets.symmetric(vertical: 16),
              ),
              child: const Text('模拟调用 Native C++ 函数'),
            ),
          ],
        ),
      ),
    );
  }
}

---

六、总结与展望

FFI 不仅是 Flutter for OpenHarmony 追求性能的终极路径，更是拥抱原生生态、复用沉淀多年 C++ 资产的唯一手段。

随着 HarmonyOS NEXT 的普及，Native 层能力的深度融合将成为高品质应用的标配。建议开发者在处理高频动画、音视频解码或加密算法时，优先考虑 FFI 方案，为鸿蒙用户带来“丝滑”的操作感受。

---

🌐 欢迎加入开源鸿蒙跨平台社区：开源鸿蒙跨平台开发者社区