RustForge 插件开发完全指南

📖 概述

RustForge 的插件系统基于 WebAssembly (Wasm)，允许您使用 Rust 安全地扩展网站功能。本指南以五运六气插件为实战案例，演示从零到一构建一个完整插件的全流程。

通过本指南，你将学习到：

• 插件的基本结构和必需的导出函数
• 如何使用 plugin_settings 存储插件数据（无需修改主程序）
• 编写前端视图并实现多语言支持（{{ key }} 语法）
• 实现 is_page_protected 进行登录保护
• 插件页面路由访问规范（/plugins/:name/index）
• 钩子系统：在主题任意位置注入插件内容（导航栏、侧边栏、页脚等），并支持多语言切换
• 利用扫描功能一键安装插件

📁 插件文件结构

plugins/wuyun-plugin/
├── Cargo.toml                 # Rust 项目配置
├── src/
│   └── lib.rs                 # 插件核心逻辑 (Wasm，极简)
├── locales/                   # 多语言翻译文件
│   ├── zh.json                # 中文翻译
│   └── en.json                # 英文翻译
├── views/                     # 前端视图片段
│   ├── index.html             # 列表页
│   ├── new.html               # 新建页
│   ├── edit.html              # 编辑页
│   └── settings.html          # 设置页（钩子管理 + 多语言配置）
└── static/                    # 静态资源
    ├── nav.html               # 导航栏片段
    ├── nav-loader.js          # 导航加载器
    └── wuyun.js               # 业务逻辑（纯前端计算）

最终编译产物为 wuyun-plugin.wasm，放在插件根目录即可被系统扫描识别。

⚙️ 插件 Rust 源码解析

极简 lib.rs（只做元数据和页面保护）

对于纯前端展示类插件，Rust 部分只需实现必需的 4 个导出函数，业务逻辑可在前端 JavaScript 中完成。

use std::alloc::{Layout, alloc};

const PLUGIN_METADATA: &str = r#"{
    "name": "wuyun-plugin",
    "version": "1.0.0",
    "author": "RustForge Team",
    "description": "五运六气管理插件"
}"#;

static mut LAST_LEN: usize = 0;

#[no_mangle]
pub extern "C" fn plugin_metadata() -> *mut u8 {
    let bytes = PLUGIN_METADATA.as_bytes();
    let len = bytes.len();
    unsafe {
        let layout = Layout::array::(len).unwrap();
        let ptr = alloc(layout) as *mut u8;
        std::ptr::copy_nonoverlapping(bytes.as_ptr(), ptr, len);
        LAST_LEN = len;
        ptr
    }
}

#[no_mangle]
pub extern "C" fn get_last_result_len() -> usize {
    unsafe { LAST_LEN }
}

#[no_mangle]
pub extern "C" fn execute(_ptr: *const u8, _len: usize) -> *mut u8 {
    let output = "{}".to_string();
    let bytes = output.into_bytes();
    let len = bytes.len();
    unsafe {
        let layout = Layout::array::(len).unwrap();
        let ptr = alloc(layout) as *mut u8;
        std::ptr::copy_nonoverlapping(bytes.as_ptr(), ptr, len);
        LAST_LEN = len;
        ptr
    }
}

#[no_mangle]
pub extern "C" fn is_page_protected(_ptr: *const u8, _len: usize) -> *mut u8 {
    // 所有页面都需要登录
    let output = "true".to_string();
    let bytes = output.into_bytes();
    let len = bytes.len();
    unsafe {
        let layout = Layout::array::(len).unwrap();
        let ptr = alloc(layout) as *mut u8;
        std::ptr::copy_nonoverlapping(bytes.as_ptr(), ptr, len);
        LAST_LEN = len;
        ptr
    }
}

Cargo.toml 配置

[package]
name = "wuyun-plugin"
version = "1.0.0"
edition = "2021"

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

🎨 前端实现

视图模板语法（重要）

<!-- ✅ 正确写法 -->
<h2>{{ wuyun_title }}</h2>
<button>{{ save }}</button>

<!-- ❌ 错误写法（不会被解析） -->
<h2>{{ t(key="wuyun_title", lang=lang) }}</h2>

导航加载器（nav-loader.js）

支持多语言的导航加载，自动替换 {{ key }} 占位符。

function loadNav(currentPage) {
    return fetch('/plugins/wuyun-plugin/static/nav.html')
        .then(res => res.text())
        .then(html => {
            const locales = window.__plugin_locales__ || {};
            for (const [key, value] of Object.entries(locales)) {
                html = html.replace(new RegExp(`\\{\\{\\s*${key}\\s*\\}\\}`, 'g'), value);
            }
            document.getElementById('user-center-nav').innerHTML = html;
            // 高亮当前页面
            document.querySelectorAll('[data-nav]').forEach(link => {
                if (link.getAttribute('data-nav') === currentPage) {
                    link.classList.add('bg-gray-100', 'font-semibold');
                }
            });
        });
}

JavaScript 多语言辅助

const __t = (key, fallback) => (window.__plugin_locales__ && window.__plugin_locales__[key]) || fallback || key;

🌐 多语言支持

插件只需在根目录下创建 locales/ 文件夹，放入对应语言的 JSON 文件即可实现多语言。钩子内容中的 {{ key }} 也会被自动翻译，并且插件设置页可以按语言版本分别管理钩子内容。

语言包文件格式

locales/zh.json：

{
    "wuyun_title": "五运六气",
    "add_record": "添加记录",
    "name": "姓名",
    "year": "年份",
    "time": "时间 (MM-DD)",
    "save": "保存",
    "cancel": "取消",
    "edit": "编辑",
    "delete": "删除"
}

locales/en.json：

{
    "wuyun_title": "Five Yun and Six Qi",
    "add_record": "Add Record",
    "name": "Name",
    "year": "Year",
    "time": "Time (MM-DD)",
    "save": "Save",
    "cancel": "Cancel",
    "edit": "Edit",
    "delete": "Delete"
}

🔌 钩子系统

钩子系统允许插件在主题的任意位置注入内容，无需修改主题模板。支持导航栏、侧边栏、页脚、头部等任何位置，并且钩子内容可以按语言版本独立设置。

工作原理

• 主题模板中放置钩子占位符：{{ hooks.nav | safe }}
• 插件通过管理 API 创建钩子记录，指定 hook_name 和 lang（语言代码）
• 主程序渲染时，会根据当前语言加载对应版本的钩子；若不存在，则回退到通用（lang=''）钩子
• 钩子内容支持 {{ key }} 多语言占位符，由主程序自动翻译
• 若插件被禁用，其所有钩子将不会在前台显示

钩子数据结构

钩子的多语言策略

系统加载钩子时遵循以下优先级：

1. 优先加载当前语言（lang='zh'）的钩子。
2. 若不存在，则回退到通用（lang=''）钩子。
3. 若仍不存在，该钩子位置为空。
4. 多个钩子按 sort_order 排序后合并输出。
5. 若插件被禁用，其所有钩子均被忽略。

在主题模板中使用

在主题模板的任意位置添加钩子占位符，使用 | safe 防止转义：

<!-- 导航栏 -->
<ul>
    <li><a href="/">首页</a></li>
    {{ hooks.nav | safe }}
    <li><a href="/about">关于我们</a></li>
</ul>

<!-- 侧边栏 -->
<div class="sidebar">
    {{ hooks.sidebar | safe }}
</div>

<!-- 页脚 -->
<footer>
    {{ hooks.footer | safe }}
</footer>

插件管理钩子

在插件设置页面中，为不同语言版本分别创建或编辑钩子内容。建议从系统设置动态获取可用语言列表，生成下拉选择框。

// 获取系统可用语言
const resp = await fetch('/api/admin/lang-settings');
const data = await resp.json();
const availableLangs = data.available_langs || [];

// 创建钩子时指定语言
fetch('/api/admin/plugins/wuyun/hooks', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        hook_name: 'nav',
        content: '
{{ wuyun_title }}
',
        sort_order: 10,
        lang: 'zh',   // 或 '' 表示通用
        enabled: true
    })
});

钩子 API

💾 插件数据存储

插件数据通过 plugin_settings 表以 JSON 格式存储，完全无需修改主程序。

读写接口

使用示例

// 读取数据
fetch(`/api/admin/plugins/${PLUGIN_NAME}/settings`)
    .then(r => r.json())
    .then(data => {
        const records = data.records || [];
        // 渲染列表
    });

// 写入数据
fetch(`/api/admin/plugins/${PLUGIN_NAME}/settings`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ records: [...] })
});

🧭 插件路由访问

访问规范

页面保护

在 lib.rs 中实现 is_page_protected 函数，返回 "true" 的页面需要登录才能访问。

#[no_mangle]
pub extern "C" fn is_page_protected(_ptr: *const u8, _len: usize) -> *mut u8 {
    // 所有页面都需要登录
    alloc_string("true")
}

未登录用户访问受保护页面会被重定向到 /plugins/{name}/login（可修改为全局后台登录页）。

🚀 开发与部署流程

1. 编写 Rust 插件

1. 创建项目 cargo new my-plugin --lib
2. 配置 Cargo.toml，设置 crate-type = ["cdylib"]
3. 编写 src/lib.rs，实现 4 个导出函数
4. 编译为 wasm：cargo build --target wasm32-unknown-unknown --release
5. 复制 target/wasm32-unknown-unknown/release/my_plugin.wasm 到插件根目录，命名为 my-plugin.wasm

2. 创建前端文件

• views/：存放 HTML 页面片段（如 index.html, new.html）
• static/：存放 JS、CSS 等静态资源
• locales/：存放 zh.json 和 en.json 语言包
• 钩子支持：在设置页提供钩子管理功能，支持为不同语言版本添加/编辑钩子

3. 安装与启用

1. 将插件文件夹放入 plugins/ 目录
2. 登录管理后台 → 插件管理 → 点击 "扫描可用插件"
3. 在列表中找到插件，点击 "安装"
4. 安装完成后，确保插件状态为 "启用"

4. 访问测试

• 访问 /plugins/my-plugin/index 查看列表页
• 访问 /plugins/my-plugin/new 测试新建功能
• 访问 /plugins/my-plugin/settings 管理钩子（测试多语言钩子切换）
• 切换语言验证多语言翻译是否生效
• 检查主题页面中钩子内容是否正确显示