FFI 实战:用 dart:ffi 调用 C / Rust / Go 原生库
第 10 章 · FFI 实战:用 dart:ffi 调用 C / Rust / Go 原生库
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 本章目标
- 10.2 FFI 是什么,和 cgo / MethodChannel 差在哪
- 10.3 三种语言的导出方式
- 10.4 C:从 .h 到 Dart 绑定
- 头文件
- 手写绑定
- 用 ffigen 生成绑定
- 第三种写法:@Native(声明式注解)
- 10.5 Rust:cdylib + #[no_mangle]
- 10.6 Go:-buildmode=c-shared + //export
- 10.7 字符串:所有权矩阵(本章最重要的一张表)
- 10.8 回调:让原生代码调用 Dart
- 10.9 在 isolate 里跑 FFI:别阻塞 UI 线程
- 10.10 平台差异:.so / .dylib / .dll
- 10.11 FFI vs MethodChannel:怎么选
- 10.12 运行与验证
- 10.13 本章小结 + C/Go 对照清单
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 |
一键构建脚本:
# 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):
==> 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 绑定
头文件
// 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 类型"。
手写绑定
// 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'),
...;
}
三个要点:
-
两套 typedef 缺一不可:
Native是给 FFI 看的(必须是ffi类型),Dart是给你用的(普通的int/double/String语义)。 -
lookupFunction找不到符号会抛ArgumentError——符号名拼错是最常见的失败,尤其 Go 的大小写。 -
Dart 的
int是 64 位,C 的int32_t是 32 位。传超出范围的值会静默截断:text add_i32(2147483647, 1) = -2147483648(int32 回绕)这与 C 的
int64_t隐式转int32_t完全一致,编译器不会救你。
用 ffigen 生成绑定
符号多了以后手写 typedef 容易错。ffigen 从 .h 直接生成:
# 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']
dart pub add --dev ffigen
dart run ffigen --config ffigen.yaml
生成物给了一个类,用法非常直:
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 函数:
// 符号名直接写进注解,调用点没有 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]
# examples/ch10-ffi/native/rust/Cargo.toml
[lib]
crate-type = ["cdylib"] # 输出 C ABI 动态库;rlib/staticlib 都不行
// 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 特有的点:
- Rust ABI 不能跨语言。必须
extern "C";否则参数传递方式由编译器决定,Dart 完全对不上。 #[no_mangle]禁止符号修饰。没有它符号会变成_ZN8add_rust7add_i3217h...这种。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
// 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() 产生的副本 |
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); // 还给原生分配器
}
}
四条铁律:
- 谁分配谁释放——用分配方的释放函数。
calloc.free放不掉 Rust 的CString,free_string也放不掉 Dart 的calloc内存(在 Windows 上尤其明显,CRT 不同)。 toDartString()会复制,复制之后原生内存才能释放;反过来,不要把toDartString()的结果当成原生指针用。Pointer没有生命周期检查。原生侧释放后再用 = use-after-free = segfault,Dart 的异常机制救不了你。- 频繁调用时,字符串转换是主要开销(UTF-8 编解码 + 分配)。热路径上考虑
Pointer<Uint8>+asTypedList零拷贝传数组。
示例测试里有一个"每种绑定重复 200 次字符串往返"的用例,用来兜住明显的泄漏/崩溃;真正的泄漏检测要用平台工具(Linux: valgrind / ASan;macOS: Instruments / leaks;Windows: CRT debug heap)。
10.8 回调:让原生代码调用 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 函数还没跑呢。
生命周期是最容易出错的地方:
// 错误: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 帧。标准做法:
// 在后台 isolate 里加载并调用
final int result = await Isolate.run(() {
final DynamicLibrary lib = DynamicLibrary.open(path);
final f = lib.lookupFunction<Int64Native, Int64Dart>('heavy_compute');
return f(iterations);
});
示例里有一个可直接运行的实现与回归测试:
// 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;
});
$ dart run
=== isolate 中调用 ===
后台 isolate 计算 sum(i^2, 1..100000) = 333338333350000 (5ms)
注意事项:
- 每个 isolate 都要自己
DynamicLibrary.open(库句柄不能跨 isolate 共享)。 - 传进 isolate 的只能是"可发送"的数据——不能用
Pointer(指针是进程地址,跨 isolate 虽然同一进程但被禁止发送)。所以要传数据而不是指针,或者用TransferableTypedData。 - 回调(
NativeCallable)属于创建它的 isolate,不能跨 isolate 用。 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 做的最小抽象:
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 运行与验证
# 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 真实输出(节选):
动态库目录: .../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 老兵的三句话:
- FFI 的难点不是"怎么调",而是内存所有权——每个
Pointer都要能回答"谁分配、谁释放"。 - 字符串往返永远走"复制 + 双份释放":入参用
calloc自己放,返回值让原生库自己放。 - 崩溃不可捕获。原生代码的 segfault 就是整个 Dart 进程的 segfault,所以 FFI 边界要有测试兜住。
下一章讲状态管理:从 setState 的局限出发,经 InheritedWidget/ChangeNotifier,最后落到 Riverpod——综合项目(ch16/ch17)的主力方案。