Native on zed的博客

UniFFI 实战手册：Android + Rust 混合开发

Sun, 11 Jan 2026 13:59:24 +0800

UniFFI 的核心价值是减少手写 JNI 胶水代码：Rust 侧定义类型和函数，UniFFI 生成 Kotlin 绑定，让 Android 侧像调用普通 Kotlin API 一样访问 Rust Core。

核心结论

UniFFI 适合把 Rust Core 暴露给 Kotlin/Swift 等上层语言。
Android 场景下通常生成 Kotlin binding，再加载 Rust .so。
类型边界要保持简单，避免跨 FFI 传递复杂平台对象。
异步、回调、错误类型要提前设计，否则后期迁移成本很高。
推荐优先使用过程宏模式，减少 .udl 文件和实现之间的漂移。

一、环境与配置

1.1 `Cargo.toml` 依赖配置

在 Rust 项目根目录的 Cargo.toml 中，注意 crate-type 和 uniffi 的版本一致性：

[lib]
# "cdylib" 是必须的，用于生成 Android 可用的 .so 文件
crate-type = ["cdylib"]
name = "rust_lib_core" # 通用库名

[dependencies]
# features = ["tokio"] 开启异步支持，这对高性能 App 至关重要
uniffi = { version = "0.28", features = ["tokio"] }
thiserror = "1.0"
# 用于驱动异步运行时
tokio = { version = "1", features = ["full"] }
# 常用库推荐
log = "0.4"
android_logger = "0.13" # 让 Rust 日志输出到 Logcat

[build-dependencies]
# ⚠️ 警告：这里的版本必须和 dependencies 里的版本严格一致！
uniffi = { version = "0.28", features = ["build"] }

1.2 Rust 入口文件 (`lib.rs`)

// 这一行宏会自动生成 JNI 胶水代码，不可省略
uniffi::setup_scaffolding!();

// 初始化日志系统（建议放在某个 init 函数中调用）
#[uniffi::export]
fn init_logger() {
 android_logger::init_once(
 android_logger::Config::default().with_min_level(log::Level::Debug),
 );
}

1.3 `uniffi.toml` 配置文件

在项目根目录（与Cargo.toml同级）创建uniffi.toml：

[bindings.kotlin]
# 生成的 Kotlin 代码的包名，必须与 Android 项目结构匹配
package_name = "com.example.app.core"
# 编译生成的 .so 文件名 (去掉 lib 前缀)。例如 librust_lib_core.so -> rust_lib_core
cdylib_name = "rust_lib_core"

1.4 Gradle 集成（Android 侧）

在 Android 项目的 app/build.gradle.kts 中，你需要让 Gradle 自动调用 uniffi-bindgen。 (注：市面上有 net.navatwo.uniffi 等插件，但手动配置更稳定)

关键步骤逻辑：

Cargo 编译 Rust -> 生成 .so
uniffi-bindgen 读取 .so -> 生成 .kt
将 .kt 加入 Android 源码集

二、类型系统：通信的词汇

2.1 基础类型映射表

Rust	Kotlin	说明
`u8` / `i8`	`UByte` / `Byte`	-
`i32`	`Int`	-
`u64`	`ULong`	坑点：Kotlin 的 Unsigned 类型使用起来较繁琐，有时建议在 Rust 层转为 `i64` (Long) 传输时间戳。
`f32` / `f64`	`Float` / `Double`	-
`bool`	`Boolean`	-
`String`	`String`	自动处理 UTF-8 转换，内存安全。
`Vec<u8>`	`ByteArray`	重点：二进制流、文件数据、protobuf。
`Vec<T>`	`List<T>`	列表，会有拷贝开销。
`Option<T>`	`T?`	完美映射为 Kotlin 的可空类型。
`HashMap<K, V>`	`Map<K, V>`	映射为 Kotlin Map。

2.2 Record – 纯数据包（DTO）

性质：值拷贝。在传输时进行序列化/反序列化。
用途：配置对象，一次性状态快照。

#[derive(uniffi::Record)]
pub strcut AppConfig {
 pub api_endpoint: String,
 pub timeout_ms: u32,
 pub max_retries: u8
}

2.3 Enum – 状态与事件

性质：根据是否携带数据，生成不同的Kotlin结构
用途：状态机、业务事件、错误码。

#[derive(uniffi::Enum)]
pub enum NetworkState {
 Disconnected,
 Connecting,
 Connected { session_id: String, ping_ms: u32 },
 Failed(String)
}

2.4 Object（对象）– 核心服务

性质：引用传递。传递的是Handle(u64)
生命周期: 有Arc智能指针管理。
线程安全：必须实现Sync + Send。这意味着内部状态通常需要Mutex

use std::sync::Mutex;

#[derive(uniffi::Object)]
pub struct CoreService {
 inner: Mutex<ServiceState>
}

#[uniffi::export]
imple CoreService {
 #[uniffi::constructor]
 pub fn new() -> Self {
 Self { inner : Mutex::new(ServiceState::default()) }
 }
}

三、函数与交互

3.1 异步函数(Async) – 彻底告别卡顿

原理： Rust Future通过UniFFI的polling机制桥接到Kotlin Coroutines。

Rust写法:

#[uniffi::export]
impl CoreService {
 pub async fn perform_action(&self, param: String) -> Result<String, CoreError> {
 tokio::time::sleep(std::time::Duration::from_secs(2)).await;
 if param.is_empty() {
 return Err(CoreError::InvalidParam);
 }
 Ok("success_result".into())
 }
}

3.2 回调接口 – 反向通知

场景：Rust后台线程需要通知Android UI更新

Rust定义

#[uniffi::export(callback_interface)]
pub trait StateListener: Send + Sync {
 fn on_progress(&self, percent: u32);
 fn on_log(&self, msg: String);
}

Kotlin实现

class AndroidListener: StateListener {
 override fun onProgress(percent: UInt) {
 MainScope().launch {
 progressBar.progress = percent.toInt()
 }
 }
 override fun onLog(msg: String) {
 Log.d("RustCore", msg)
 }
}

四、高级技巧

4.1 自定义类型 – 包装`SystemTime`

场景：你想在接口里直接使用Rust的SystemTime，但Uniffi不支持。你需要把它转换为u64传给Kotlin。

Rust实现：

创建一个NewType 包装器（如果需要）或直接为你的类型实现 UniffiCustomTypeConverter。
此处演示简单包装模式（UniFFI 尚不支持直接对标准库类型实现 Converter，通常使用 NewType）。

#[derive(uniffi::Object)]
pub struct RustTime(std::time::SystemTime);

#[uniffi::export]
impl RustTime {
 #[uniffi::constructor]
 pub fn now() -> Self {
 Self(std::time::SystemTime::now())
 }

 // 转为毫秒时间戳给 Kotlin 用
 pub fn to_millis(&self) -> u64 {
 self.0.duration_since(std::time::UNIX_EPOCH)
 .unwrap_or_default()
 .as_millis() as u64
 }
}

4.2 错误处理

让异常携带数据，实现精细化UI交互。

#[derive(Debug, thiserror::Error, uniffi::Error)]
pub enum ActionError {
 #[error("操作受限，冷却中: {retry_after}秒")]
 Throttled { retry_after: u32 },
}

4.3 内存管理

UniFFI的对象虽然有GC兜底，但在高性能场景下，必须手动释放重资源对象。

// 在 Android ViewModel 中
override fun onCleared() {
 super.onCleared()
 coreService.destory()
}

Clean Architecture + Rust：Kotlin UI 与 Rust Core 的边界

Sun, 11 Jan 2026 13:02:10 +0800

把 Rust 引入 Android 项目时，最重要的问题不是“能不能调用 Rust”，而是“哪些逻辑值得放到 Rust”。如果边界不清楚，跨语言调用只会增加复杂度。

核心结论

Kotlin 适合处理 Android 平台能力、生命周期、权限、UI 和依赖注入。
Rust 适合承载可跨平台复用、计算密集、协议解析或强一致性的核心逻辑。
Domain 层应该定义稳定接口和模型，隔离 UI 与具体实现。
FFI 边界要尽量窄，避免 Kotlin 和 Rust 互相泄漏内部细节。
使用 Rust 的收益必须大于构建、调试、类型映射和团队学习成本。

架构模型

graph LR
UI["Kotlin UI / Compose"]
VM["ViewModel"]
Domain["Domain Interfaces / Models"]
Adapter["Kotlin Adapter / UniFFI Binding"]
Rust["Rust Core"]
UI --> VM
VM --> Domain
Domain --> Adapter
Adapter --> Rust

职责划分：

层	职责
Kotlin UI	渲染、交互、生命周期
ViewModel	UI 状态管理、调用 UseCase
Domain	接口、领域模型、用例边界
Adapter	Kotlin 与 Rust 类型适配
Rust Core	核心逻辑、协议、计算、跨平台能力

Domain 作为契约

Domain 层不应该关心底层是 Kotlin、Rust 还是 C++。

interface GameRepository {
 suspend fun getGameDetails(id: String): Game
 suspend fun startSession(config: SessionConfig): SessionResult
}

ViewModel 只依赖这个接口：

class GameViewModel(
 private val repository: GameRepository,
) : ViewModel()

Rust 只是接口的一种实现来源。

Kotlin 侧边界

Kotlin 保留这些职责：

Compose / View UI；
Android 生命周期；
权限、通知、Intent 等平台能力；
Hilt/Koin 依赖装配；
UI 状态和一次性事件。

不要把 Android Context、Activity、View 等平台对象传进 Rust Core。

Rust 侧边界

Rust 更适合：

协议解析；
编解码辅助逻辑；
复杂业务规则；
高并发网络核心；
跨 Android/iOS/桌面复用的能力。

Rust 不适合直接处理：

Android 生命周期；
UI 状态；
权限弹窗；
依赖注入容器；
和平台强绑定的对象。

依赖装配

Hilt 负责把 Rust 实现装配成 Domain 接口：

@Module
@InstallIn(SingletonComponent::class)
object DataModule {
 @Provides
 fun provideGameRepository(
 rustService: RustGameService,
 ): GameRepository {
 return RustGameRepository(rustService)
 }
}

这样 UI 层不需要知道 Rust 细节。

回看清单

Rust Core 应该服务架构边界，而不是制造新的耦合。
Domain 层定义稳定协议，Kotlin/Rust 都围绕它实现。
FFI 传输模型要简单、明确、可版本化。
平台对象留在 Kotlin，核心逻辑放到 Rust。
引入 Rust 前先问：这段逻辑是否真的需要跨平台或高性能核心。

Rust JNI 环境配置：Android NDK、cargo-ndk 与 ABI

Wed, 15 Oct 2025 13:45:38 +0800

Android 调用 Rust 的第一步不是写 JNI，而是把交叉编译环境配稳定。这里重点整理 Rust target、NDK、cargo-ndk 和 ABI 的关系。

核心结论

Android 上运行的是 .so 动态库，不是普通桌面可执行文件。
Rust 需要安装 Android 对应 target。
NDK 提供 Android 平台的交叉编译工具链。
cargo-ndk 可以简化 ABI、platform、输出目录等配置。
先验证能产出 .so，再接 Kotlin/JNI。

环境检查

rustc --version
cargo --version

确认 Android SDK 和 NDK 已安装。通常可以在 Android Studio 里检查：

Settings / Preferences
 -> Android SDK
 -> SDK Tools
 -> NDK

安装 Rust Android target

常见 target：

rustup target add aarch64-linux-android
rustup target add armv7-linux-androideabi
rustup target add x86_64-linux-android

对应关系：

Android ABI	Rust target
`arm64-v8a`	`aarch64-linux-android`
`armeabi-v7a`	`armv7-linux-androideabi`
`x86_64`	`x86_64-linux-android`

实际发布通常优先保证 arm64-v8a。

安装 cargo-ndk

cargo install cargo-ndk

验证：

cargo ndk --version

配置 NDK 路径

常见环境变量：

export ANDROID_HOME="$HOME/Library/Android/sdk"
export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/<version>"

检查：

ls "$ANDROID_NDK_HOME"

应该能看到 toolchains、platforms 或相关 NDK 目录。

编译 Rust 动态库

Cargo.toml：

[lib]
crate-type = ["cdylib"]

编译：

cargo ndk \
 -t arm64-v8a \
 -o ../android/app/src/main/jniLibs \
 build --release

输出结构通常是：

app/src/main/jniLibs/
└── arm64-v8a/
 └── librust_core.so

Kotlin 侧加载

object NativeBridge {
 init {
 System.loadLibrary("rust_core")
 }
}

注意：System.loadLibrary("rust_core") 不写 lib 前缀，也不写 .so 后缀。

回看清单

ABI、Rust target、.so 输出目录必须对应。
NDK 是交叉编译工具链，cargo-ndk 是简化工具。
crate-type = ["cdylib"] 是生成 Android .so 的关键。
Kotlin 加载库名时去掉 lib 和 .so。
先跑通单 ABI，再扩展多 ABI 和 Gradle 自动化。

Android Rust 混合开发入门：NDK、JNI、ABI 与 .so

Wed, 15 Oct 2025 11:55:59 +0800

Android 与 Rust 混合开发的核心链路是：Rust 编译成 Android 可加载的 .so，Kotlin/Java 通过 JNI 或 UniFFI 访问其中的能力。

核心结论

NDK 提供 Android Native 开发和交叉编译工具链。
Rust 代码最终要编译成对应 ABI 的 .so。
JNI 是 JVM 与 Native 世界之间的桥。
.so 需要放到 jniLibs/<abi>/ 或由构建流程打进 APK/AAB。
只有在跨平台复用、性能、协议/算法核心等场景下，引入 Rust 才更值得。

什么是NDK?

NDK = Native Development Kit(原生开发工具包)

一句话解释

NDK 是 Android 提供的工具集，让你能用 C/C++/Rust 等原生语言开发 Android 应用的一部分。

Android应用的两种开发方式

┌─────────────────────────────────────────┐
│ Android 应用 │
├─────────────────────────────────────────┤
│ │
│ 方式 1: Java/Kotlin (Android SDK) │
│ ┌──────────────────────────────────┐ │
│ │ Kotlin/Java 代码 │ │
│ │ ↓ │ │
│ │ 编译为 DEX 字节码 │ │
│ │ ↓ │ │
│ │ 在 Dalvik/ART 虚拟机运行 │ │
│ └──────────────────────────────────┘ │
│ │
│ 方式 2: C/C++/Rust (Android NDK) │
│ ┌──────────────────────────────────┐ │
│ │ C/C++/Rust 代码 │ │
│ │ ↓ │ │
│ │ 编译为 .so 文件 (机器码) │ │
│ │ ↓ │ │
│ │ 直接在 CPU 上运行 (无虚拟机) │ │
│ └──────────────────────────────────┘ │
│ │
│ 两者通过 JNI 桥接 │
└─────────────────────────────────────────┘

为什么需要NDK？

对比理解

纯 Java/Kotlin(SDK):

优点:
✅ 开发简单
✅ 跨设备兼容好
✅ 调试方便
缺点:
❌ 性能有限 (虚拟机开销)
❌ 某些功能无法实现
❌ 无法复用 C/C++ 库

NDK(C/C++/Rust)

优点:
✅ 性能极高 (接近机器码)
✅ 可以复用现有 C/C++ 库
✅ 直接访问硬件
✅ 跨平台代码复用
缺点:
❌ 开发复杂
❌ 调试困难
❌ 需要为不同 CPU 编译

NDK工作原理

完整流程

第 1 步: 写 Rust 代码
┌────────────────────────┐
│ // Rust 代码 │
│ pub fn add(a: i32, b: i32) -> i32 {
│ a + b │
│ } │
└────────────────────────┘
↓
第 2 步: NDK 编译
┌────────────────────────┐
│ NDK 工具链编译 │
│ - 交叉编译 │
│ - 针对 ARM/x86 CPU │
└────────────────────────┘
↓
第 3 步: 生成 .so 文件
┌────────────────────────┐
│ librust_lib.so │
│ (机器码,可直接运行) │
└────────────────────────┘
↓
第 4 步: Android 加载
┌────────────────────────┐
│ System.loadLibrary("rust_lib")
│ │
│ external fun add(a: Int, b: Int): Int
└────────────────────────┘
↓
第 5 步: JNI 调用
┌────────────────────────┐
│ Kotlin → JNI → Rust │
│ val result = add(5, 3) │
│ // result = 8 │
└────────────────────────┘

NDK包含什么？

NDK工具集

$ANDROID_NDK_HOME/
├── build/ # 构建脚本
├── toolchains/ # 编译器工具链
│ ├── aarch64-linux-android/ # ARM64 编译器
│ ├── arm-linux-androideabi/ # ARM32 编译器
│ ├── x86/ # x86 编译器
│ └── x86_64/ # x86_64 编译器
├── platforms/ # Android API 级别的头文件
├── sources/ # 示例代码
└── sysroot/ # 系统库

编译器

NDK 提供了针对不同 CPU 架构的编译器:
ARM64 (arm64-v8a): 现代手机 (主流)
ARM32 (armeabi-v7a): 老手机
x86: 模拟器
x86_64: 模拟器

.so文件是什么？

理解.so文件

.so = Shared Object (共享对象)
类似于:
- Windows 的 .dll 文件
- macOS 的 .dylib 文件
作用:
- 包含编译后的机器码
- 可以被多个程序共享使用

.so文件示例

# 查看 .so 文件
ls android/app/src/main/jniLibs/arm64-v8a/
# librust_lib.so ← 这就是编译后的 Rust 代码

# 查看文件信息
file librust_lib.so
# librust_lib.so: ELF 64-bit LSB shared object, ARM aarch64, ...

# 查看导出的函数
nm -D librust_lib.so | grep Java
# Java_com_example_rustdemo_RustBridge_add
# Java_com_example_rustdemo_RustBridge_reverseString

开发流程概览

完整环境安装、Rust target、cargo-ndk 和 ABI 输出目录已经单独放在《Rust JNI 环境配置》里。这里保留概念流程：

Rust 代码
 -> NDK / cargo-ndk 交叉编译
 -> 生成对应 ABI 的 .so
 -> 打进 APK/AAB
 -> Kotlin 通过 JNI 或 UniFFI 调用

NDK核心概念

JNI(Java Native Interface)

JNI是桥梁:

┌──────────────┐ ┌──────────────┐
│ Kotlin │ JNI │ Rust │
│ (虚拟机) │ ◄─────► │ (原生码) │
└──────────────┘ └──────────────┘
数据传递:
Kotlin Int ↔ Rust i32
Kotlin String ↔ Rust String
Kotlin IntArray ↔ Rust &[i32]

交叉编译

什么是交叉编译?

你在 x86_64 电脑上开发
↓
但手机是 ARM64 架构
↓
需要"交叉编译": 在 x86_64 上编译出 ARM64 代码
↓
NDK 提供了交叉编译工具链

ABI(Application Binary Interface)

不同CPU需要不同的**.so**文件:

arm64-v8a/libmylib.so → ARM64 手机
armeabi-v7a/libmylib.so → ARM32 手机
x86/libmylib.so → x86 模拟器
x86_64/libmylib.so → x86_64 模拟器

什么时候用NDK?

应该用NDK的场景

1. 性能关键代码
- 图像/视频处理
- 音频处理
- 大量数学计算
- 加密/解密
2. 复用现有代码
- 已有 C/C++ 库
- 跨平台代码 (iOS/Android 共享)
3. 保护核心算法
- 防止反编译
- 商业逻辑保护
4. 访问底层功能
- 硬件控制
- 系统调用

不应该用NDK的场景

1. 简单业务逻辑
- 按钮点击
- 数据展示
- 网络请求
2. 快速开发
- 原型验证
- MVP 阶段
3. 团队不熟悉 C/C++/Rust
- 维护成本高
- Bug 难以调试

常用排查工具

# 查看 .so 文件信息
readelf -h libmylib.so
# 查看导出的函数
nm -D libmylib.so
# 反汇编 (调试用)
objdump -d libmylib.so

总结

NDK是什么？

NDK = 让你用 C/C++/Rust 开发 Android 的工具包
作用:
1. 提供交叉编译工具链
2. 编译出 .so 机器码文件
3. 通过 JNI 与 Kotlin 交互
4. 获得原生性能
适用场景:
- 高性能计算
- 复用 C/C++ 库
- 跨平台开发

关键概念

NDK: 工具包
JNI: 桥梁 (Kotlin ↔ 原生代码)
.so: 编译后的机器码
ABI: 不同 CPU 架构
流程:
Rust 代码 → NDK 编译 → .so 文件 → JNI 调用 → Kotlin 使用

Native on zed的博客

UniFFI 实战手册：Android + Rust 混合开发

核心结论

一、环境与配置

1.1 Cargo.toml 依赖配置

1.2 Rust 入口文件 (lib.rs)

1.3 uniffi.toml 配置文件

1.4 Gradle 集成（Android 侧）

二、类型系统：通信的词汇

2.1 基础类型映射表

2.2 Record – 纯数据包（DTO）

2.3 Enum – 状态与事件

2.4 Object（对象）– 核心服务

三、函数与交互

3.1 异步函数(Async) – 彻底告别卡顿

3.2 回调接口 – 反向通知

四、高级技巧

4.1 自定义类型 – 包装SystemTime

4.2 错误处理

4.3 内存管理

Clean Architecture + Rust：Kotlin UI 与 Rust Core 的边界

核心结论

架构模型

Domain 作为契约

Kotlin 侧边界

Rust 侧边界

依赖装配

回看清单

Rust JNI 环境配置：Android NDK、cargo-ndk 与 ABI

核心结论

环境检查

安装 Rust Android target

安装 cargo-ndk

配置 NDK 路径

编译 Rust 动态库

Kotlin 侧加载

回看清单

Android Rust 混合开发入门：NDK、JNI、ABI 与 .so

核心结论

什么是NDK?

Android应用的两种开发方式

为什么需要NDK？

对比理解

NDK工作原理

完整流程

NDK包含什么？

NDK工具集

编译器

.so文件是什么？

理解.so文件

.so文件示例

开发流程概览

NDK核心概念

JNI(Java Native Interface)

交叉编译

ABI(Application Binary Interface)

什么时候用NDK?

应该用NDK的场景

不应该用NDK的场景

常用排查工具

总结

NDK是什么？

关键概念

1.1 `Cargo.toml` 依赖配置

1.2 Rust 入口文件 (`lib.rs`)

1.3 `uniffi.toml` 配置文件

4.1 自定义类型 – 包装`SystemTime`