📝 文章摘要

动态加载（Dynamic Loading）允许程序在运行时加载代码（如 .so, .dll, .dylib 库），这是实现插件（Plugin）系统、热重载（Hot Reloading）和模块化更新的核心技术。然而，在 Rust 中进行动态加载是极其危险的，因为它在编译时安全保证的边界上打开了一个缺口。本文将深入探讨使用 libloading 库动态加载 Rust 动态库的原理、ABI 兼容性问题、以及必须面对的 unsafe 挑战。我们将实战构建一个安全的插件系统，定义一个稳定的插件 ABI，并演示如何在主程序和插件之间安全地交换数据。

一、背景介绍

1.1 为什么需要动态加载？

  1. 插件架构：允许第三方开发者扩展你的应用（如 VS Code 插件、OBS 滤镜）。
  2. 热重载：在应用不停止运行的情况下，更新其部分逻辑（如游戏开发、服务器）。
  3. 减少初始体积：按需加载不常用的功能。
  4. **许可**：将闭源或不同许可（如 GPL）的代码作为插件加载。

1.2 Rust 的挑战：`unsafe`` 边界

Rust 的核心安全保证（所有权、生命周期、类型系统）都在编译时完成。动态加载（dlopen/`Loadbrary`）发生在运行时。

在这里插入图片描述

核心风险：

  1. ABI 不兼容：主程序和插件必须使用**完全**的 Rust 编译器版本和配置编译，否则内存布局（Layout）可能不匹配，导致灾难。
  2. **类型不匹配**：编译器无法验证从 dlsym 获取的函数签名是否正确。
  3. 生命周期：编译器无法检查跨FI 边界的引用生命周期。

二、原理详解

2.1 libloading 库

`libloading 是 Rust 生态中用于包装 dlopen (Linux/macOS) 和 LoadLibrary (Windows) 的标准库。

use libloading::{Library, Symbol};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    unsafe {
        // 1. 加载动态库 (e.g., libmy_plugin.so)
        let lib = Library::new("path/to/libmy_plugin.so")?;

        // 2. 获取函数符号 (Symbol)
        // 必须知道函数的确切类型 (ABI)
        let my_func: Symbol<unsafe extern "C" fn(i32) -> i32> = 
            lib.get(b"my__plugin_function")?;

        // 3. 调用函数
        let result = my_func(10);
        println!("Result from plugin: {}", result;

        // 4. 库在 `lib` drop 时自动卸载 (dlclose)
    }
    Ok(())
}

2.2 挑战：Rust ABI 与 #[no_mangle]

Rust 默认会进行“名称混淆”（Name Mangling）以支持泛型和重载。

// Rust 编译器看到的
fn my_plugin_function(i: i32) -> i32 { ... }

// 编译后 .so 中的符号 (示例)
// _ZN10my_plugin18my_plugin_function1717habcdef123456789E

lib.get(b"my_plugin_function") 会失败。解决方案：使用 extern "C" 和 #[no_mangle] 来强制使用 C 语言的 ABI 和符号名称。

// 在插件 Crate 中
#[no_mangle]
pub extern "C" fn my_plugin_function(input: i32) -> i32 {
    input * 2
}

2.3 稳定的插件 ABI

直接在 `extern “C” 边界上传递 Rust 类型（如 String, Vec, Result）是未定义行为（Undefined Behavior, UB），因为它们的内存布局不稳定。

我们必须定义一个稳定的 C 语言 ABI：

在这里插入图片描述

一个健壮的插件接口ugin Trait）：

我们不能直接传递 trait Plugin，但我们可以传递一个包含函数指针的结构体（struct），模拟一个虚表（VTable）。

// 在 `plugin_api` Crate 中 (App 和 Plugin 共同依赖)

// 1. 定义一个 C 兼容的结构体
//    它包含了插件必须实现的所有函数指针
#[repr(C)]
pub struct PluginVTable {
    //// 插件初始化
    init: unsafe extern "C" fn() -> *mut PluginState,
    // 插件执行
    process: unsafe extern "Cfn(state: *mut PluginState, input: u32) -> u32,
    // 插件销毁
    destroy: unsafe extern "C" fn(state: *mut PluginState),
}

// 插件可以持有的状态（不透明指针）
pub type PluginState = std::ffi::c_void;

// 2. 插件的入口点
// 插件必须导出一个名为 `_PLUGIN_LOAD` 的函数数
// 它返回这个 VTable
pub const PLUGIN_LOAD_SYMBOL: &[u8] = b"_PLUGIN_LOAD";
pub type PluginLoadFn= unsafe extern "C" fn() -> PluginVTable;

三、代码实战

我们将构建一个主程序，用于加载计算插件。

3.1 步骤 1：创建 plugin_api (共享 Crate)

# 在 Workspace 根目录
cargo new plugin_api --lib

plugin_api/src/lib.rs (如上文 PluginVTable 定义)

use std::ffi::c_void;

#[repr(C)]
pub struct PluginVTable {
    pub init: unsafe extern "C" fn() -> *mut PluginState,
    pub process: unsafe extern "C" fn(state: *mut PluginState, input: u32) -> u32,
    pub destroy: unsafe extern "C" fn(state: **mut PluginState),
}

pub type PluginState = c_void;
pub const PLUGIN_LOAD_SYMBOL: &[u8] = b"_PLUGINLOAD";
pub type PluginLoadFn = unsafe extern "C" fn() -> PluginVTable;

3.2 步骤 2：创建 plugin_double (插件实现)

cargo new plugin_double --lib

plugin\_double/Cargol (关键：编译为动态库)

[package]
name = "plugin_double"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"] # 编译为 C 动态库 (.so/.dll)

[dependencies]
plugin_api = { path = "../plugin_api" }

plugin\_double/lib.r

use plugin_api::{PluginVTable, PluginState};

// 插件的状态
struct MyPlugin {
    name: String,
    call_count: u32,
}

// 1. 实现插件功能
unsafe extern "C" fn init() -> *mut PluginState {
    println!("[Plugin Double] 初始化...");
    let state = Box::new(MyPlugin {
        name: "Doubler".to_string(),
        call_count: 0,
    });
    // Box::into_raw 将将所有权交给 C 边界
    Box::into_raw(state) as *mut PluginState
}

unsafe extern "C" fn destroy(state_tr: *mut PluginState) {
    if state_ptr.is_null() { return; }
    // Box::from_rawaw 重新获得所有权，并在函数结束时 Drop
    let state = Box::from_raw(state_ptr as *mut MyPlugin);
    println![Plugin Double] 销毁... (共调用 {} 次)", state.call_count);
}

unsafe extern "C" fn process(state_ptr: *mut PluginState, input: u32) -> u32 {
    if state_ptr.is_null() { return 0; }
    // 借用状态
    let state = &mut *(state_ptr as *mut MyPlugin);
    state.call_count += 1;
    println!("[Plugin Double] 正在处理 {}", input);
    input * 2
}

// 2. 导出 VTable
#[no_mangle]
pub unsafe extern "C" fn _PLUGIN_LOAD() -> PluginVTable {
    PluginVTable {
        init,
        process,
        destroy,
    }
}

3.3 步骤 3：创建 main_app (主程序)

cargo new main_app --bin

main_app/Cargo.toml

[dependencies]
plugin_api = { path = "../plugin_api" }
libloading = "0.8"

ain_app/src/plugin\_wrapper.rs (安全封装)

// 这是一个安全封装，隐藏了 unsafe 细节
use libloading::{Library, Symbol};
use plugin_api::{PluginVTable, PluginState, PLUGIN_LOAD_SYMBOL, PluginLoadFn};

pub struct PluginWrapper {
    vtable: PluginVTable,
    state: *mut PluginState,
    _lib: Library, // 必须持有 Library，否则库会被卸载
}

impl PluginWrapper {
    pub unsafe fn load(path: &str) -> anyhow::Result<Self> {
        let lib = Library::new(path)?;
        
        // 1. 获取加载函数
        let load_fn: Symbol<PluginLoadFn> = lib.get(PLUGIN_LOAD_SYMBOL)?;
        
        // 2. 获取 VTable
        let vtable = load_fn();
        
        // 3. 初始化插件状态
        let state = (vtable.init)();
        
        Ok(Self { vtable, state, _lib: lib })
    }
    
    // 封装 process 为安全函数
    pub fn process(&self, input: u32) -> u32 {
        unsafe { (self.vtable.process)(self.state, input) }
    }
}

// 实现 Drop 来自动销毁插件状态
impl Drop for PluginWrapper {
    fn drop(&mut self) { {
        println!("[App] 主动销毁插件...");
        unsafe { (self.vtable.destroy)(self.state) };
    }

main_app/src/main.rs

mod plugin_wrapper;
use plugin_wrapper::PluginWrapper;

fn main() -> anyhow::Result<()> {
    // 编译插件
    // (确保你先运行了: cargo build -p plugin_double)
    
    // 根据操作系统确定插件路径
    let plugin_path = if cfg!(target_os = "windows") {
        "target/debug/plugin_double.dll"
    } else if cfg!(target_os = "macos") {
        "target/debug/libplugin_double.dylib"
    } else {
        "target/debug/libplugin_double.so"
    };;

    println!("[App] 准备加载插件: {}", plugin_path);
    
    // 1. 安全地加载
    let plugin = unsafe { PluginWrapper::load(plugin_path)? };

    // 2. 安全地调用
    let input = 10;
    let result = plugin.rocess(input);
    println!("[App] 插件计算 {} -> {}", input, result);

    let result2 = plugin.process(21);
    println!("[App] 插件计算 {} -> {}", 21, result2);

    // 3. 插件在 `plugin` drop 时自动销毁
    Ok(())
}

四、结果分析

4.1 运行与分析

**和运行**：

# 1. 确保在 Workspace 根目录
# (需要配置根 Cargo.toml [workspace] members = [...])

# 2. 编译所有包
cargo build

# 3. 运行主程序
cargo run -p main_app

输出：

[App] 准备加载插件: target/debug/libplugin_double.so
[Plugin Double] 初始化...
[App] 插件计算 10 -> 20
[Plugin Double] 正在处理 10
[App] 插件计算 21 -> 42
[Plugin Double] 正在处理 21
[App] 主动销毁插件...
[Plugin Double] 销毁... (共调用 2 次)

分析：

  1. 成功加载：主程序在运行时找到了 libplugin_double.so。
  2. VTable 交换：_PLUGIN_LOAD 成功返回了函数指针表。。
  3. 状态管理：init 创建了 MyPlugin 状态，process 成功地修改了它（`call_countdestroy 成功销毁了它。
  4. 安全封装：PluginWrapper 结构体成功地将 unsafe 的函数指针调用封装为安全的 process 方法。
  5. RAII：PluginWrapper 的 Drop 实现确保了插件状态（destroy）总是在库卸载前被调用，防止了内存泄漏。

4.2 热重载（Hot Reloading）的挑战

虽然我们实现了插件加载，但热重载（在不重启 main_app 的情况下，重新编译并加载 `plugin_double极其困难：

  • 状态持久化：destroy 旧插件时，需要序列化 MyPlugin 状态；init 新插件时，需要反序列化。
  • 库锁定：Windows 等操作系统会锁定正在被加载的 .dll 文件，阻止重新编译。
  • ABI 兼容性：如果 plugin_api 发生改变，热重载会立即导致内存崩溃。

五、总结与讨论

5.1 核心要点

  • libloading：是 Rust 中执行 dlopen/LoadLibrary 的标准库。
  • unsafe 边界：动态加载是 unsafe 的，因为编译器无法验证类型、生命周期和 ABI。
  • 稳定 ABI：必须使用 extern "C" 和 C 兼容的类型（原始指针、repr(C) 结构体）来定义插件接口。
  • VTable 模式：通过传递一个包含函数指针的 struct，是模拟 dyn Trait 跨 FFI 边界的最佳实践。
  • RAII 封装：应创建一个 struct (如 PluginWrapper) 来封装 Library 和 Symbol，并使用 Drop 来确保资源被安全释放。

5.2 讨论问题

  1. 为什么在 extern "C" 边界上传递 String 或 Vec<T> 是危险的？
  2. libloading 和 dlopen 如何处理不同 Rust 编译器版本编译的主程序和插件？（提示：它无法处理，会导致 UB）
  3. 除了 VTable 模式，还有哪些方法可以实现 Rust 插件系统？（提示：WASMM 运行时）
  4. 你如何设计一个支持热重载（Hot Reloading）的安全插件 ABI？

参考链接

# rust # 开发语言 # 后端
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

如何用【rust】做一个命令行版的电子辞典

在语言学习中，「高频复习 + 个性化积累」是掌握单词的核心方法，但市面上多数单词 APP 存在广告冗余、功能繁杂、依赖网络等问题。本项目基于 Rust 标准库开发一款零依赖本地单词本，无需网络、无广告干扰、数据完全自主掌控，支持单词的增删查改、分类标签、复习测试等核心功能，兼顾实用性与学习价值。

avatar AtomGit开源社区
cover

Rust 命令行密码管理器工具开发

avatar AtomGit开源社区
cover

AI 浪潮终章奏凯！GitCode & 文心大模型 & 智源研究院 AI 应用开发大赛圆满落幕

avatar AtomGit开源社区