《FFI 与原生库集成：C/C++/Rust 互操作》

import 'dart:ffi';
// 通过绝对路径加载（Android 上指向 .so）
final lib = DynamicLibrary.open('libnative_utils.so');
// 按平台选择加载方式
DynamicLibrary _load() {
  if (Platform.isAndroid) return DynamicLibrary.open('libnative_utils.so');
  if (Platform.isIOS || Platform.isMacOS) return DynamicLibrary.process();
  if (Platform.isWindows) return DynamicLibrary.open('native_utils.dll');
  return DynamicLibrary.open('libnative_utils.so');
}

// 声明 C 函数的 Dart 签名
typedef _AddNative = Int32 Function(Int32 a, Int32 b);
typedef AddDart = int Function(int a, int b);
// 查找符号并绑定类型
final _addNative = _load()
    .lookupFunction<_AddNative, AddDart>('add');
void main() {
  final result = _addNative(3, 4); // 7
}

import 'dart:ffi';
import 'package:ffi/ffi.dart'; // malloc 等辅助工具

// 分配一块可写内存并写入数据
final ptr = calloc<Int32>(4); // 4 个 int32
ptr[0] = 10;
ptr[1] = 20;
calloc.free(ptr);

// 定义与 C 结构体一一对应的 Dart 结构体
final class Point extends Struct {
  @Double()
  external double x;
  @Double()
  external double y;
}
// 也可以从原生返回的指针读取
Pointer<Point> p = _getPointNative();
final x = p.ref.x;

final _finalizer = NativeFinalizer(_freeNative);
class NativeHandle {
  final Pointer<Void> _ptr;
  NativeHandle(this._ptr) {
    // 注册：当本对象被回收时调用 _freeNative
    _finalizer.attach(this, _ptr);
  }
}
void _freeNative(Pointer<Void> ptr) {
  _free_native(ptr); // 调用 C 的 free
}

# pubspec.yaml 依赖
dependencies:
  ffi: ^2.1.0
  ffigen: ^16.0.0

# ffigen.yaml 配置
name: NativeUtilsBindings
description: Bindings for native_utils
output: lib/src/native_utils_bindings.dart
headers:
  entry-points:
    - 'native/native_utils.h'
  include-directives:
    - '**native_utils.h'

dart run ffigen --config ffigen.yaml

import 'package:ffi/ffi.dart';
// Dart 字符串 → C 字符串（自动分配与释放）
Pointer<Utf8> toNativeString(String value) => value.toNativeUtf8();
// C 字符串 → Dart 字符串
String fromNativeString(Pointer<Utf8> ptr) => ptr.toDartString();

final class Rect extends Struct {
  @Int32()
  external int left;
  @Int32()
  external int top;
  @Int32()
  external int right;
  @Int32()
  external int bottom;
}
// 传入：把 Dart 数据写入原生内存
final rect = calloc<Rect>();
rect.ref.left = 0;
rect.ref.top = 0;
rect.ref.right = 640;
rect.ref.bottom = 480;
// 调用原生 API
_intersectNative(rect, rect);
// 读取返回值
final area = (rect.ref.right - rect.ref.left) * (rect.ref.bottom - rect.ref.top);
calloc.free(rect);

// 在后台 Isolate 中执行耗时原生计算
Future<int> heavyComputeInBackground(int input) {
  return Isolate.run(() {
    // 这里可以安全调用耗时原生函数
    return _heavyNative(input);
  });
}
final result = await heavyComputeInBackground(42);

// src/lib.rs
use std::ffi::{CStr, CString};
use std::os::raw::c_char;

#[no_mangle]
pub extern "C" fn sum(a: i32, b: i32) -> i32 { a + b }

#[no_mangle]
pub extern "C" fn greet(name: *const c_char) -> *mut c_char {
    let name = unsafe { CStr::from_ptr(name) }.to_string_lossy();
    CString::new(format!("Hello, {}!", name)).unwrap().into_raw()
}

#[no_mangle]
pub extern "C" fn free_cstr(ptr: *mut c_char) {
    unsafe { drop(CString::from_raw(ptr)) };
}

# 编译为静态库（Android/iOS 各架构）
cargo build --release --target aarch64-linux-android
cargo build --release --target aarch64-apple-ios

pub fn fibonacci(n: u32) -> u64 {
    match n { 0 => 0, 1 => 1, _ => fibonacci(n - 1) + fibonacci(n - 2) }
}

// 生成后的 Dart 调用，完全类型安全
final result = await rustLib.api.fibonacci(n: 20);

#[no_mangle]
pub extern "C" fn divide(a: i32, b: i32) -> i32 {
    // panic 跨 FFI 边界会 UB，必须捕获
    std::panic::catch_unwind(|| a / b)
        .unwrap_or(i32::MIN) // 用哨兵值表示错误
}

// android/app/build.gradle.kts
android {
  defaultConfig {
    ndk { abiFilters += listOf("arm64-v8a", "armeabi-v7a", "x86_64") }
  }
}

# 把预编译 .so 放进 android/app/src/main/jniLibs/<abi>/

// 反模式：每像素一次 FFI 调用（极慢）
// 应改为一次性传入整个像素缓冲
for (var i = 0; i < pixels.length; i++) {
  _pixelOpNative(pixels[i]); // 万万不可
}
// 正解：整体传入指针
final buffer = calloc<Uint8>(pixels.length);
buffer.asTypedList(pixels.length).setAll(0, pixels);
_processBufferNative(buffer, pixels.length);
calloc.free(buffer);