如何将独立Rust Crate作为CLI工具插件并实现跨平台自动发现

问题背景 #

我有一个发布在crates.io上的Rust crate，可通过cargo install安装为命令行工具。当前采用libloading加载动态库插件，核心代码如下：

use libloading::Library;

pub trait Plugin {
    fn plugin_fn_1(&self);
    fn plugin_fn_2(&self);
    // ...
}

fn main() {
    let plugin_paths: Vec<OsString> = Vec::new(); // 需要填充插件路径
    let mut plugin_registry = Vec::new();
    for path in plugin_paths {
        unsafe {
            let lib = Box::leak(Box::new(Library::new(path).unwrap()));
            let plugin_entry_point = lib
                .get::<libloading::Symbol<
                    unsafe extern "C" fn() -> &'static mut dyn Plugin,
                >>(b"plugin_entry_point")
                .unwrap();
            plugin_registry.push(plugin_entry_point());
        }
    }

    for plugin in &plugin_registry {
        plugin.plugin_fn_1();
    }
    // ...
}

希望插件是可通过cargo install直接安装（无需额外参数）的独立crates，实现跨平台（Linux、Mac、Windows）自动发现已安装插件，且避免每次启动扫描大量目录。

成熟实现机制 #

1. 约定专属插件目录+注册表式发现 #

这是行业常规方案，核心思路是不扫描全局系统目录，只关注工具专属的约定目录，再通过注册表文件直接读取插件路径，彻底避免全目录扫描。

步骤1：定义跨平台的约定目录

利用dirs crate获取系统标准的应用数据目录，在此基础上创建工具专属的插件目录：

use dirs::data_dir;
use std::path::PathBuf;

fn get_plugin_dir() -> PathBuf {
    data_dir()
        .expect("无法获取系统应用数据目录")
        .join("<你的工具名称>")
        .join("plugins")
}

各平台对应的实际路径：

• Linux: $HOME/.local/share/<你的工具名称>/plugins
• Mac: $HOME/Library/Application Support/<你的工具名称>/plugins
• Windows: %APPDATA%\<你的工具名称>\plugins

步骤2：用注册表文件记录插件路径

主工具维护一个JSON格式的注册表文件，存放在上述插件目录下，直接记录已安装插件的完整路径。主工具启动时只需读取该文件，无需扫描目录。

注册表结构与加载代码：

use serde::{Deserialize, Serialize};
use std::fs;
use serde_json;

#[derive(Serialize, Deserialize, Debug)]
struct PluginRegistry {
    plugins: Vec<PathBuf>,
}

fn load_registry() -> PluginRegistry {
    let registry_path = get_plugin_dir().join("registry.json");
    if registry_path.exists() {
        let content = fs::read_to_string(&registry_path).unwrap_or_default();
        serde_json::from_str(&content).unwrap_or_else(|_| PluginRegistry { plugins: Vec::new() })
    } else {
        PluginRegistry { plugins: Vec::new() }
    }
}

步骤3：插件自动注册到约定目录

让插件在cargo install完成后，自动将自身动态库链接/复制到约定插件目录，并更新注册表：

• 插件需配置为动态库：在Cargo.toml中设置crate-type = ["cdylib"]
• 添加post-install脚本，完成注册操作（需跨平台适配）

示例插件的Cargo.toml配置（以Linux为例，可通过条件配置适配Mac/Windows）：

[package]
name = "my-tool-plugin-demo"
version = "0.1.0"
edition = "2021"

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

[dependencies]
my-tool = { version = "0.1.0", features = ["plugin-api"] }

[package.metadata.install]
post-install = """
#!/bin/bash
# 获取插件安装路径
PLUGIN_FILENAME="libmy_tool_plugin_demo.so"
PLUGIN_PATH="$CARGO_INSTALL_ROOT/lib/$PLUGIN_FILENAME"

# 创建工具插件目录
MY_TOOL_PLUGIN_DIR="$HOME/.local/share/my-tool/plugins"
mkdir -p "$MY_TOOL_PLUGIN_DIR"

# 链接插件到约定目录
ln -sf "$PLUGIN_PATH" "$MY_TOOL_PLUGIN_DIR/"

# 更新注册表
REGISTRY_PATH="$MY_TOOL_PLUGIN_DIR/registry.json"
if [ ! -f "$REGISTRY_PATH" ]; then
    echo '{"plugins": []}' > "$REGISTRY_PATH"
fi
# 避免重复添加
if ! jq -e '.plugins | index("'"$MY_TOOL_PLUGIN_DIR/$PLUGIN_FILENAME"'")' "$REGISTRY_PATH" >/dev/null 2>&1; then
    jq --arg path "$MY_TOOL_PLUGIN_DIR/$PLUGIN_FILENAME" '.plugins += [$path]' "$REGISTRY_PATH" > "$REGISTRY_PATH.tmp"
    mv "$REGISTRY_PATH.tmp" "$REGISTRY_PATH"
fi
"""

步骤4：主工具加载插件

修改主工具的main函数，直接从注册表读取插件路径：

fn main() {
    let registry = load_registry();
    let plugin_paths = registry.plugins;
    let mut plugin_registry = Vec::new();

    for path in plugin_paths {
        if !path.exists() {
            eprintln!("插件路径不存在，已跳过: {}", path.display());
            continue;
        }
        unsafe {
            match Library::new(&path) {
                Ok(lib) => {
                    let lib = Box::leak(Box::new(lib));
                    match lib.get::<libloading::Symbol<unsafe extern "C" fn() -> &'static mut dyn Plugin>>(b"plugin_entry_point") {
                        Ok(plugin_entry_point) => {
                            plugin_registry.push(plugin_entry_point());
                        }
                        Err(e) => eprintln!("加载插件入口失败: {}", e),
                    }
                }
                Err(e) => eprintln!("加载插件库失败: {}", e),
            }
        }
    }

    for plugin in &plugin_registry {
        plugin.plugin_fn_1();
    }
}

2. 补充注意事项 #

• 跨平台脚本适配：Windows需用PowerShell脚本，Mac的动态库后缀是.dylib，Windows是.dll，可通过Cargo的target_os条件配置区分不同平台的脚本。
• 插件卸载处理：需在插件的post-uninstall脚本中，从注册表移除对应路径并删除链接文件。
• 安全校验：加载动态库涉及unsafe代码，建议添加插件签名验证，确保插件来源可信。
• 容错处理：主工具需处理注册表文件损坏、插件路径不存在等异常情况，避免崩溃。

内容的提问来源于stack exchange，提问作者ChrisB