跳到正文
CH 10工程化Dart + FFI14 分钟阅读

FFI 实战:用 dart:ffi 调用 C / Rust / Go 原生库

第 10 章 · FFI 实战:用 dart:ffi 调用 C / Rust / Go 原生库

本章示例examples/ch10-ffi在线阅读源码下载 zip

run

$cd examples/ch10-ffi/native && ./build_all.sh
$cd examples/ch10-ffi && dart pub get && dart run

已验证

  • dart analyze 0 告警、dart test 18 个用例全绿(C 手写绑定 / C ffigen 生成绑定 / Rust / Go)
  • 完整工程已打包:打包下载
本章目录 · 17 节

10.1 本章目标

  • 用 dart:ffi 调用 C、Rust、Go 三种语言写的动态库,覆盖数值、字符串往返、回调三种基本形态;
  • 彻底搞懂跨语言内存所有权:谁分配、谁释放、什么时候会泄漏;
  • 会用手写 lookupFunction 绑定,也会用 ffigen 从头文件生成绑定;
  • 理解 C ABI、符号导出、动态库加载(dlopen / LoadLibrary)在三个平台的差异;
  • 知道 FFI 和平台通道(ch15)的分工,以及什么时候该把 FFI 调用丢进 isolate。

这是 C/Go 读者最有主场优势的一章:你们已经知道 ABI、指针和 malloc/free,缺的只是 Dart 这一侧的写法。

10.2 FFI 是什么,和 cgo / MethodChannel 差在哪

方案 调用方向 通信方式 开销 适用
dart:ffi Dart → C ABI 直接函数调用 纳秒级 高性能计算、复用现有 C/Rust/Go 库
平台通道(ch15) Dart ↔ 原生(Kotlin/Swift/C++) 消息序列化 微秒~毫秒 调平台 API(蓝牙、传感器、系统服务)
cgo(Go 侧) Go ↔ C 直接调用 + 调度器让出 微秒级 Go 程序调 C 库

dart:ffi 不做序列化:它按 C ABI 传参数(寄存器/栈),和你写 C 调用 C 没有本质区别。所以它能做到"每帧调用几千次"而平台通道做不到。

代价:

  • 你需要自己管理内存和类型(Int32 / Double / Pointer<Utf8>…);
  • 原生库必须按平台编译并随应用分发;
  • 原生代码崩溃(segfault)会带走整个 Dart 进程——没有异常可以捕获。

10.3 三种语言的导出方式

语言 构建命令 导出标记 产物
C cc -shared -fPIC -o libadd_c.so c/add.c 普通函数 + 头文件(extern "C") .so / .dylib / .dll
Rust cargo build --release(crate-type = ["cdylib"]) #[no_mangle] pub extern "C" fn libadd_rust.so / .dylib / add_rust.dll
Go go build -buildmode=c-shared -o libadd_go.so go/add.go //export Name + package main libadd_go.so / .dylib / add_go.dll

一键构建脚本:

bashnative/build_all.sh源文件
# examples/ch10-ffi/native/build_all.sh(节选)
case "$(uname -s)" in
  Darwin) EXT=dylib; CFLAGS=(-dynamiclib) ;;
  Linux)  EXT=so;    CFLAGS=(-shared -fPIC) ;;
  *)      EXT=dll;   CFLAGS=(-shared) ;;
esac

cc "${CFLAGS[@]}" -O2 -o "$OUT/libadd_c.$EXT" c/add.c
(cd rust && cargo build --release --quiet)
cp "rust/target/release/libadd_rust.$EXT" "$OUT/libadd_rust.$EXT"
(cd go && CGO_ENABLED=1 go build -buildmode=c-shared -o "$OUT/libadd_go.$EXT" add.go)

本次真实验证(macOS arm64):

text
==> C     (libadd_c.dylib)
==> Rust  (libadd_rust.dylib)
==> Go    (libadd_go.dylib)
libadd_c.dylib        33 KB
libadd_go.dylib      1.2 MB     ← Go 运行时被链接进来了
libadd_rust.dylib    353 KB

Go 的产物明显大一圈:c-shared 会把 Go runtime 一起链接进库。这是用 Go 写动态库的固定代价。

10.4 C:从 .h 到 Dart 绑定

头文件

cnative/c/add.h源文件
// examples/ch10-ffi/native/c/add.h
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif

int32_t add_i32(int32_t a, int32_t b);
double mul_f64(double a, double b);
char *concat_strings(const char *a, const char *b);
void free_string(char *s);
int32_t apply_cb(int32_t (*cb)(int32_t), int32_t x);

#ifdef __cplusplus
}
#endif

extern "C" 是给 C++ 编译器看的(禁止名字修饰);Dart 侧只关心"符号名 + C 类型"。

手写绑定

dartlib/bindings/c_bindings.dart源文件
// examples/ch10-ffi/lib/bindings/c_bindings.dart
typedef AddI32Native = Int32 Function(Int32 a, Int32 b);   // 原生签名
typedef AddI32Dart = int Function(int a, int b);           // Dart 签名

class CLibrary implements AddLibrary {
  CLibrary._(DynamicLibrary lib)
      : _addI32 = lib.lookupFunction<AddI32Native, AddI32Dart>('add_i32'),
        _concat = lib.lookupFunction<ConcatNative, ConcatDart>('concat_strings'),
        _applyCb = lib.lookupFunction<ApplyCbNative, ApplyCbDart>('apply_cb'),
        ...;
}

三个要点:

  1. 两套 typedef 缺一不可:Native 是给 FFI 看的(必须是 ffi 类型),Dart 是给你用的(普通的 int/double/String 语义)。

  2. lookupFunction 找不到符号会抛 ArgumentError——符号名拼错是最常见的失败,尤其 Go 的大小写。

  3. Dart 的 int 是 64 位,C 的 int32_t 是 32 位。传超出范围的值会静默截断:

    text
    add_i32(2147483647, 1) = -2147483648(int32 回绕)
    

    这与 C 的 int64_t 隐式转 int32_t 完全一致,编译器不会救你。

用 ffigen 生成绑定

符号多了以后手写 typedef 容易错。ffigen 从 .h 直接生成:

yamlffigen.yaml源文件
# examples/ch10-ffi/ffigen.yaml
name: CAdd
output: 'lib/bindings/c_bindings_generated.dart'
headers:
  entry-points:
    - 'native/c/add.h'
functions:
  include: ['add_i32', 'mul_f64', 'concat_strings', 'free_string', 'apply_cb']
bash
dart pub add --dev ffigen
dart run ffigen --config ffigen.yaml

生成物给了一个类,用法非常直:

dart
final CAdd add = CAdd(NativeLoader.open('add_c'));
add.add_i32(40, 2);      // 42
add.mul_f64(1.5, 4.0);   // 6.0

final Pointer<Char> out = add.concat_strings(a, b);   // char* → Pointer<Char>
add.free_string(out);

注意生成版把 char* 映射成 Pointer<Char>(Int8),而 package:ffi 的 Utf8 是 Uint8。两者都是 1 字节,读字符串时 result.cast<Utf8>().toDartString() 即可。

手写绑定 ffigen
可读性 高,能读懂每个 typedef 低,但不用读
维护成本 头文件一改就要改 重新生成即可
额外依赖 无 ffigen + libclang
适合 少量符号、教学、排查 ABI 真实项目

示例里两种都有,测试都跑通(C 与 C (ffigen) 两组)。

第三种写法:@Native(声明式注解)

Dart 2.17+ 还提供了 @Native 注解,把外部函数声明成普通的 external 函数:

dart
// 符号名直接写进注解,调用点没有 lookupFunction 的样板
@Native<Int32 Function(Int32, Int32)>(symbol: 'add_i32')
external int addI32(int a, int b);

@Native<Double Function(Double, Double)>(symbol: 'mul_f64')
external double mulF64(double a, double b);
  • 默认在调用时从进程符号表(DynamicLibrary.process())解析,所以必须先把库加载进进程 (例如应用启动时 DynamicLibrary.open(...),或把库静态链接进主二进制——iOS 就是这条路);
  • 配合 native assets(库级 @Native + DefaultAsset),构建系统可以自动编译并绑定符号, 连 DynamicLibrary.open 都省掉。该机制仍在演进,本教程为跨平台可控选择了 lookupFunction;
  • 三种写法(lookupFunction / ffigen / @Native)产出的 ABI 完全一样,区别只在"胶水代码长什么样"。
写法 胶水 运行期解析 适用
lookupFunction 手写 typedef + lookup 打开库时 任意平台,最可控(本章主用)
ffigen 生成 打开库时 符号多的真实项目
@Native 注解声明 调用时(进程符号表) 静态链接 / native assets

10.5 Rust:cdylib + #[no_mangle]

tomlnative/rust/Cargo.toml源文件
# examples/ch10-ffi/native/rust/Cargo.toml
[lib]
crate-type = ["cdylib"]     # 输出 C ABI 动态库;rlib/staticlib 都不行
rustnative/rust/src/lib.rs源文件
// examples/ch10-ffi/native/rust/src/lib.rs
#[no_mangle]
pub extern "C" fn add_i32(a: i32, b: i32) -> i32 {
    a.wrapping_add(b)
}

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

#[no_mangle]
pub unsafe extern "C" fn free_string(s: *mut c_char) {
    if !s.is_null() { drop(CString::from_raw(s)); }
}

#[no_mangle]
pub extern "C" fn apply_cb(cb: extern "C" fn(i32) -> i32, x: i32) -> i32 { cb(x) }

三个 Rust 特有的点:

  1. Rust ABI 不能跨语言。必须 extern "C";否则参数传递方式由编译器决定,Dart 完全对不上。
  2. #[no_mangle] 禁止符号修饰。没有它符号会变成 _ZN8add_rust7add_i3217h... 这种。
  3. CString::into_raw / CString::from_raw 是所有权转移的标准配对:into_raw 把所有权交给调用方(Dart),from_raw 收回来让 Rust 的分配器释放。用不同分配器释放会崩,所以必须还给 free_string,不能 calloc.free。

字符串用 CStr/CString 而不是 &str/String:后者没有 NUL 结尾保证,也不是 C ABI 布局。

Rust 侧的 unsafe 只出现在两处:解引用裸指针、from_raw。其余是安全代码——这是 Rust 写 FFI 的正常形态。

10.6 Go:-buildmode=c-shared + //export

gonative/go/add.go源文件
// examples/ch10-ffi/native/go/add.go
package main

/*
#include <stdint.h>
#include <stdlib.h>

typedef int32_t (*cb_t)(int32_t);
static int32_t invoke_cb(uintptr_t p, int32_t x) { return ((cb_t)p)(x); }
*/
import "C"

import "unsafe"

//export AddI32
func AddI32(a, b C.int32_t) C.int32_t { return a + b }

//export ConcatStrings
func ConcatStrings(a, b *C.char) *C.char {
	return C.CString(C.GoString(a) + C.GoString(b))
}

//export FreeString
func FreeString(s *C.char) { C.free(unsafe.Pointer(s)) }

//export ApplyCb
func ApplyCb(cb C.uintptr_t, x C.int32_t) C.int32_t { return C.invoke_cb(cb, x) }

func main() {}

四个坑,全是 Go 特有的:

坑 说明
package main + 空 main() c-shared 只支持 main 包
符号名大写开头 Go 的导出规则;Dart 侧要查 AddI32 不是 add_i32
必须 CGO_ENABLED=1 无 cgo 就没有 C ABI 导出
回调要先转成 uintptr,再借一层 C 函数调用 cgo 不允许 Go 直接调函数指针;invoke_cb 这个 static inline 就是桥

C.CString 用 malloc 分配,所以释放必须用 C.free(FreeString)——和 Rust 的 CString::from_raw 属于两套分配器,不能混用。

顺带一个 Go 的问题:-buildmode=c-shared 会把整个 Go runtime 编进库里,体积 1MB 起,且启动时初始化 runtime。要极致小体积,C/Rust 更合适。

10.7 字符串:所有权矩阵(本章最重要的一张表)

步骤 谁分配 谁释放 Dart 侧写法
Dart → 原生 const char* Dart(calloc) Dart(calloc.free) a.toNativeUtf8() … calloc.free(pa)
原生 → Dart char*(C/Rust/Go 分配) 原生 原生(调它的 free_string) p.toDartString() 复制后 free_string(p)
Dart 侧字符串 Dart GC Dart GC toDartString() 产生的副本
dart
String concat(String a, String b) {
  final Pointer<Utf8> pa = a.toNativeUtf8();   // calloc
  final Pointer<Utf8> pb = b.toNativeUtf8();
  Pointer<Utf8> result = nullptr;
  try {
    result = _concat(pa, pb);
    if (result == nullptr) throw StateError('native returned NULL');
    return result.toDartString();              // 复制成 Dart String
  } finally {
    calloc.free(pa);
    calloc.free(pb);
    if (result != nullptr) _freeString(result); // 还给原生分配器
  }
}

四条铁律:

  1. 谁分配谁释放——用分配方的释放函数。calloc.free 放不掉 Rust 的 CString,free_string 也放不掉 Dart 的 calloc 内存(在 Windows 上尤其明显,CRT 不同)。
  2. toDartString() 会复制,复制之后原生内存才能释放;反过来,不要把 toDartString() 的结果当成原生指针用。
  3. Pointer 没有生命周期检查。原生侧释放后再用 = use-after-free = segfault,Dart 的异常机制救不了你。
  4. 频繁调用时,字符串转换是主要开销(UTF-8 编解码 + 分配)。热路径上考虑 Pointer<Uint8> + asTypedList 零拷贝传数组。

示例测试里有一个"每种绑定重复 200 次字符串往返"的用例,用来兜住明显的泄漏/崩溃;真正的泄漏检测要用平台工具(Linux: valgrind / ASan;macOS: Instruments / leaks;Windows: CRT debug heap)。

10.8 回调:让原生代码调用 Dart

dart
int applyCallback(int Function(int x) fn, int x) {
  final NativeCallable<Int32 Function(Int32)> cb =
      NativeCallable<Int32 Function(Int32)>.isolateLocal(
    (int v) => fn(v),
    exceptionalReturn: -1,       // Dart 回调抛异常时给原生侧的值
  );
  try {
    return _applyCb(cb.nativeFunction, x);   // 函数指针
  } finally {
    cb.close();                              // 必须关,否则回调永远活着
  }
}

NativeCallable 有两种:

构造 返回类型 执行时机 用途
.isolateLocal(...) 任意(需 exceptionalReturn) 同步,在调用线程上直接执行 原生同步回调(本例)
.listener(...) 只能是 void 异步,投递到 isolate 的事件队列 原生侧随时通知(事件、日志)

编译期踩坑:最初用的是 .listener(...),直接报 The return type of the function passed to 'NativeCallable.listener' must be 'void'。 因为 listener 是"异步回调",原生侧拿到返回值时 Dart 函数还没跑呢。

生命周期是最容易出错的地方:

dart
// 错误:native 保存了指针,函数返回后 cb 被 close,之后回调就是野指针
final cb = NativeCallable<...>.isolateLocal(...);
someNativeLib.registerCallback(cb.nativeFunction);
// cb 离开作用域 → close → native 再调用 = 崩溃

// 正确:把 cb 存成字段,等 unregister 之后再 close
late final NativeCallable<...> _cb = ...;
@override
void dispose() {
  lib.unregisterCallback();
  _cb.close();
  super.dispose();
}

Go 侧还有一层:Dart 的函数指针是 Pointer<NativeFunction<...>>,Go 需要 uintptr,所以传 cb.nativeFunction.address,Go 内部再借 C 函数转回函数指针(见 invoke_cb)。

10.9 在 isolate 里跑 FFI:别阻塞 UI 线程

dart:ffi 的调用发生在当前 isolate 的线程上。一次 50ms 的原生计算 = UI 卡 3 帧。标准做法:

dart
// 在后台 isolate 里加载并调用
final int result = await Isolate.run(() {
  final DynamicLibrary lib = DynamicLibrary.open(path);
  final f = lib.lookupFunction<Int64Native, Int64Dart>('heavy_compute');
  return f(iterations);
});

示例里有一个可直接运行的实现与回归测试:

dartlib/ffi_isolate.dart源文件
// examples/ch10-ffi/lib/ffi_isolate.dart
Future<int> sumSquaresViaFfi({int n = 100000}) => Isolate.run<int>(() {
      final CLibrary lib = CLibrary.open();   // 每个 isolate 自己打开
      var sum = 0;
      for (var i = 1; i <= n; i++) {
        sum += lib.mulF64(i.toDouble(), i.toDouble()).toInt();  // 真 FFI 调用
      }
      return sum;
    });
text
$ dart run
=== isolate 中调用 ===
后台 isolate 计算 sum(i^2, 1..100000) = 333338333350000 (5ms)

注意事项:

  1. 每个 isolate 都要自己 DynamicLibrary.open(库句柄不能跨 isolate 共享)。
  2. 传进 isolate 的只能是"可发送"的数据——不能用 Pointer(指针是进程地址,跨 isolate 虽然同一进程但被禁止发送)。所以要传数据而不是指针,或者用 TransferableTypedData。
  3. 回调(NativeCallable)属于创建它的 isolate,不能跨 isolate 用。
  4. Isolate.run 的闭包可以捕获普通 Dart 值(会被复制),但捕不了 Pointer/NativeCallable。

Flutter 里对应 compute(fn, arg);规则一样:只传纯数据。

10.10 平台差异:.so / .dylib / .dll

平台 扩展名 加载 API Dart 侧
Linux .so dlopen / dlsym DynamicLibrary.open('libadd_c.so')
macOS .dylib dlopen / dlsym DynamicLibrary.open('libadd_c.dylib')
Windows .dll LoadLibrary / GetProcAddress DynamicLibrary.open('add_c.dll')
Android .so dlopen(限制路径) DynamicLibrary.open('libadd_c.so'),库放 jniLibs/<abi>/
iOS .framework / 静态 .a 没有通用 dlopen DynamicLibrary.process() 查符号,必须静态链接进主二进制

loader.dart 做的最小抽象:

dart
static String get extension {
  if (Platform.isMacOS || Platform.isIOS) return 'dylib';
  if (Platform.isWindows) return 'dll';
  return 'so'; // Linux / Android
}

static DynamicLibrary open(String stem) =>
    DynamicLibrary.open(pathOf(stem));   // libadd_c.so / libadd_c.dylib / add_c.dll

Windows 还有个额外差异:没有 lib 前缀,所以 prefix 按平台返回 ''。

Search path 也是坑:DynamicLibrary.open('libfoo.so') 会走系统搜索路径(LD_LIBRARY_PATH / DYLD_LIBRARY_PATH / PATH)。生产环境应该给绝对路径,或者把库放进应用可执行文件旁边。示例用"从当前目录向上找 build/native"来兼容 dart run/dart test,也支持 CH10_NATIVE_DIR 覆盖。

桌面打包时(ch17):

  • macOS:.dylib 放进 .app/Contents/Frameworks/,并在 Xcode 里加 "Copy Files" 阶段;
  • Linux:放进可执行文件同目录或 /usr/lib/<app>/;
  • Windows:放进 .exe 同目录(Windows 会先搜 exe 所在目录)。

10.11 FFI vs MethodChannel:怎么选

需求 选择
复用已有的 C/C++/Rust/Go 库 FFI
CPU 密集计算(图像、加解密、压缩、解析) FFI + isolate
调平台 API(传感器、蓝牙、相机、通知、文件选择器) 平台通道
需要访问 Android/iOS 的 Java/Kotlin/Swift 对象 平台通道
每次调用开销要小(每帧多次) FFI
团队只有 Kotlin/Swift 经验 平台通道

两者也能配合:平台通道拿权限/配置,FFI 做重活。

生态背景:Dart 正在推 native assets(在 pubspec.yaml 声明原生构建),目标是让"把 C/Rust 源码随包发布、由 flutter build 自动编译"变成一等公民。目前仍需自己管构建产物,本章的脚本形态是当下最稳的做法。

10.12 运行与验证

bash
# 1. 先构建原生库(必须!否则测试会提示"无法加载原生库")
cd examples/ch10-ffi/native && ./build_all.sh

# 2. Dart 侧
cd examples/ch10-ffi
dart pub get && dart analyze && dart test && dart run

dart run 真实输出(节选):

text
动态库目录: .../examples/ch10-ffi/build/native
当前平台扩展名: .dylib

=== C ===
add_i32(40, 2)      = 42
mul_f64(1.5, 4.0)   = 6.0
concat("hello, ", "dart") = hello, dart
applyCallback(x*3, 14)    = 42
...  (Rust / Go / C (ffigen) 输出完全相同)

三种语言 add_i32 结果: [42, 42, 42, 42]
三种语言 concat 结果: [ab, ab, ab, ab]
add_i32(2147483647, 1) = -2147483648(int32 回绕)

=== isolate 中调用 ===
后台 isolate 计算 sum(i^2, 1..100000) = 333338333350000 (5ms)

dart test 的 18 个用例覆盖:

  • 每种绑定(C 手写 / C ffigen / Rust / Go)的数值、字符串、回调;
  • 四种实现的返回值完全一致;
  • int32 溢出在四种实现下都是回绕;
  • 字符串路径重复 200 次不崩不泄漏(粗粒度回归)。

10.13 本章小结 + C/Go 对照清单

主题 C Go Rust Dart 侧 陷阱
导出 C ABI 普通函数 + .h //export + c-shared #[no_mangle] extern "C" lookupFunction / ffigen Go 符号大写、Rust 忘 no_mangle
动态库 .so/.dylib/.dll 同左 同左 DynamicLibrary.open Windows 没有 lib 前缀
加载方式 dlopen cgo 链接 dlopen open / process iOS 不能 dlopen
整数 int32_t C.int32_t i32 Int32 / int int32↔int64 静默截断
字符串 char* *C.char *mut c_char Pointer<Utf8> 分配器不能混用
内存 malloc/free C.CString/C.free CString::into_raw/from_raw calloc / toNativeUtf8 谁分配谁释放
回调 函数指针 uintptr + C 桥 extern "C" fn NativeCallable listener 只能 void;忘了 close
并行 线程 goroutine 线程 isolate 指针不能跨 isolate

给 C/Go 老兵的三句话:

  1. FFI 的难点不是"怎么调",而是内存所有权——每个 Pointer 都要能回答"谁分配、谁释放"。
  2. 字符串往返永远走"复制 + 双份释放":入参用 calloc 自己放,返回值让原生库自己放。
  3. 崩溃不可捕获。原生代码的 segfault 就是整个 Dart 进程的 segfault,所以 FFI 边界要有测试兜住。

下一章讲状态管理:从 setState 的局限出发,经 InheritedWidget/ChangeNotifier,最后落到 Riverpod——综合项目(ch16/ch17)的主力方案。