跳到主要内容

Tauri 前后端通信详解：Commands、Events、Channels 及其他通信方式

TauriRustJavascript桌面应用开发CommandsEventsChannels
鱼雪

在现代桌面应用开发中，Tauri 框架凭借其轻量级、高性能和安全性，成为开发者们构建跨平台应用的首选工具之一。Tauri 允许开发者使用现代前端框架（如 React、Vue 或 Svelte）构建用户界面，同时利用 Rust 语言处理高效且安全的后端逻辑。然而，前后端之间的高效通信是构建功能丰富且稳定的 Tauri 应用的关键。本文将详细介绍 Tauri 中前后端通信的主要方式——Commands（命令）、Events（事件） 及 Channels（通道），并通过示例代码帮助您更好地理解和应用这些技术。

目录​

  1. Tauri 简介
  2. 前后端通信方式概述
  3. Commands、Events 与 Channels 的对比
  4. 示例代码
  5. 权限配置示例
  6. 错误处理
  7. 最佳实践与安全性
  8. 性能优化
  9. 实际案例
  10. 总结
  11. 参考资源

Tauri 简介​

Tauri 是一个用于构建跨平台桌面应用的框架，支持 Windows、macOS 和 Linux。它利用前端技术（如 HTML、CSS、JavaScript）构建用户界面，并使用 Rust 处理后端逻辑。与 Electron 相比，Tauri 生成的应用体积更小，性能更优，且具备更高的安全性。

前后端通信方式概述​

在 Tauri 框架中，前端（通常使用 JavaScript 框架如 React、Vue 或 Svelte）与后端（Rust 编写）之间的通信是实现应用功能的核心。Tauri 提供了多种通信机制，主要包括 Commands（命令）、Events（事件） 和 Channels（通道）。除此之外，还有一些其他的通信方式，如在 Rust 中执行 JavaScript 代码。以下将详细介绍这些通信方式、它们的区别及适用场景。

Commands（命令）​

Commands 是前端调用后端 Rust 函数的主要方式。通过命令，前端可以请求后端执行特定任务并获取结果。这种通信方式类似于前端发起的远程过程调用（RPC）。

使用场景​

  • 执行复杂逻辑��需要后端处理的数据计算、文件操作、数据库交互等。
  • 获取后端数据：例如，从数据库获取数据并在前端展示。
  • 安全性需求：通过命令调用，能够在 Tauri 的安全模型下细粒度地控制权限。

实现步骤​

  1. 在 Rust 后端定义命令

    使用 #[tauri::command] 宏定义一个可供前端调用的函数。

    src-tauri/src/lib.rs
    #[tauri::command]
    fn my_custom_command() {
      println!("我被 JavaScript 调用了！");
    }

    fn main() {
      tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![my_custom_command])
        .run(tauri::generate_context!())
        .expect("运行 Tauri 应用时出错");
    }

    :::note命令名称必须唯一。:::

    :::note由于胶水代码生成的限制，在 lib.rs 文件中定义的命令不能标记为 pub。如果将其标记为公共函数，您将看到如下错误：

    error[E0255]: the name `__cmd__command_name` is defined multiple times
      --> src/lib.rs:28:8
       |
    27 | #[tauri::command]
       | ----------------- previous definition of the macro `__cmd__command_name` here
    28 | pub fn x() {}
       |        ^ `__cmd__command_name` reimported here
       |
       = note: `__cmd__command_name` must be defined only once in the macro namespace of this module

    :::

  2. 在前端调用命令

    使用 @tauri-apps/api 提供的 invoke 方法调用后端命令。

    前端 JavaScript 代码示例（如 React 组件）
    import { invoke } from '@tauri-apps/api/core';

    async function greetUser() {
        try {
            const greeting = await invoke('my_custom_command');
            console.log(greeting); // 输出: "我被 JavaScript 调用了！"
        } catch (error) {
            console.error('调用命令时出错:', error);
        }
    }

    // 在适当的生命周期钩子中调用 greetUser

  3. 配置权限

    在 tauri.conf.json 中，通过 Capabilities 和 Permissions 配置命令的访问权限，确保命令的安全调用。

    tauri.conf.json 示例
    {
        "$schema": "https://raw.githubusercontent.com/tauri-apps/tauri/dev/tooling/cli/schema.json",
        "package": {
            "productName": "Pomodoro Timer",
            "version": "0.1.0"
        },
        "tauri": {
            "windows": [
                {
                    "label": "main",
                    "title": "ToDo Pomodoro",
                    "width": 800,
                    "height": 600,
                    "resizable": true,
                    "fullscreen": false,
                    "decorations": true,
                    "transparent": false,
                    "alwaysOnTop": false,
                    "visible": true,
                    "url": "http://localhost:3000",
                    "webviewAttributes": {
                        "webPreferences": {
                            "nodeIntegration": false
                        }
                    }
                }
            ],
            "security": {
                "capabilities": [
                    {
                        "identifier": "greet-capability",
                        "description": "Allows the main window to greet users.",
                        "windows": ["main"],
                        "permissions": ["core:default"]
                    }
                ]
            },
            "bundle": {
                "active": true,
                "targets": "all",
                "identifier": "com.yuxuetr.pomodoro",
                "icon": [
                    "icons/32x32.png",
                    "icons/128x128.png",
                    "icons/128x128@2x.png",
                    "icons/icon.icns",
                    "icons/icon.ico"
                ]
            }
        }
    }

Events（事件）​

Events 是 Tauri 中实现后端向前端推送消息的机制。与 Commands 不同，Events 是单向的，适用于需要实时通知前端的场景。

使用场景​

  • 状态更新通知：后端状态变化时通知前端
  • 长时间任务进度：报告后台任务的执行进度
  • 系统事件通知：如系统状态变化、文件变动等

实现步骤​

  1. 在 Rust 后端发送事件

    src-tauri/src/lib.rs
    use tauri::Manager;

    #[tauri::command]
    async fn start_process(window: tauri::Window) {
        // 模拟一个耗时操作
        for i in 0..100 {
            window.emit("process-progress", i).unwrap();
            std::thread::sleep(std::time::Duration::from_millis(100));
        }
    }

  2. 在前端监听事件

    import { listen } from '@tauri-apps/api/event';

    // 监听进度事件
    await listen('process-progress', (event) => {
        console.log('Progress:', event.payload);
    });

Channels（通道）​

Channels 提供了一种双向的、持久的通信通道，特别适合需要持续数据交换的场景。

使用场景​

  • 流式数据传输：如实时日志、数据流
  • 长连接通信：需要保持持续通信的场景
  • 复杂的双向数据交换：需要前后端频繁交互的功能

实现示例​

  1. 在 Rust 后端创建通道

    src-tauri/src/lib.rs
    use tauri::plugin::{Builder, TauriPlugin};
    use tauri::{Runtime, State, Window};
    use std::collections::HashMap;
    use std::sync::{Mutex, mpsc};

    #[derive(Default)]
    struct ChannelState(Mutex<HashMap<String, mpsc::Sender<String>>>);

    #[tauri::command]
    async fn create_channel(
        channel_id: String,
        state: State<'_, ChannelState>,
        window: Window,
    ) -> Result<(), String> {
        let (tx, mut rx) = mpsc::channel(32);
        state.0.lock().unwrap().insert(channel_id.clone(), tx);

        tauri::async_runtime::spawn(async move {
            while let Some(message) = rx.recv().await {
                window
                    .emit(&format!("channel:{}", channel_id), message)
                    .unwrap();
            }
        });

        Ok(())
    }

  2. 在前端使用通道

    import { listen } from '@tauri-apps/api/event';
    import { invoke } from '@tauri-apps/api';

    // 创建并使用通道
    async function setupChannel() {
        const channelId = 'my-channel';
        await invoke('create_channel', { channelId });

        await listen(`channel:${channelId}`, (event) => {
            console.log('Received:', event.payload);
        });
    }

在 Rust 中执行 JavaScript​

Tauri 还支持从 Rust 后端直接执行 JavaScript 代码，这提供了另一种前后端交互的方式。

实现示例​

src-tauri/src/lib.rs
#[tauri::command]
async fn execute_js(window: tauri::Window) -> Result<String, String> {
    // 执行 JavaScript 代码
    window
        .eval("console.log('从 Rust 执行的 JavaScript')")
        .map_err(|e| e.to_string())?;

    // 执行带返回值的 JavaScript
    let result = window
        .eval("(() => { return 'Hello from JS'; })()")
        .map_err(|e| e.to_string())?;

    Ok(result)
}

Commands、Events 与 Channels 的对比​

特性Commands（命令）Events（事件）Channels（通道）
调用方向前端 → 后��后端 → 前端双向
响应类型同步/异步异步异步
使用场景一次性请求响应状态通知持续数据交换
数据流单次请求单次响应单向推送双向持续
适用性通用操作状态更新流式传输

示例代码​

Commands 示例​

完整的文件操作示例：

src-tauri/src/main.rs
use std::fs;
use tauri::command;

#[command]
async fn read_file(path: String) -> Result<String, String> {
    fs::read_to_string(path)
        .map_err(|e| e.to_string())
}

#[command]
async fn write_file(path: String, contents: String) -> Result<(), String> {
    fs::write(path, contents)
        .map_err(|e| e.to_string())
}

fn main() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![read_file, write_file])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
// 前端调用示例
import { invoke } from '@tauri-apps/api/tauri';

async function handleFileOperations() {
    try {
        // 写入文件
        await invoke('write_file', {
            path: 'test.txt',
            contents: 'Hello, Tauri!',
        });

        // 读取文件
        const content = await invoke('read_file', {
            path: 'test.txt',
        });
        console.log('File content:', content);
    } catch (error) {
        console.error('File operation failed:', error);
    }
}

Events 示例​

文件监控示例：

src-tauri/src/main.rs
use notify::{Watcher, RecursiveMode, watcher};
use tauri::Manager;
use std::time::Duration;

#[tauri::command]
async fn watch_directory(window: tauri::Window, path: String) -> Result<(), String> {
    let (tx, rx) = std::sync::mpsc::channel();

    let mut watcher = watcher(tx, Duration::from_secs(2)).map_err(|e| e.to_string())?;

    watcher.watch(&path, RecursiveMode::Recursive).map_err(|e| e.to_string())?;

    tauri::async_runtime::spawn(async move {
        for res in rx {
            match res {
                Ok(event) => {
                    window.emit("file-change", event).unwrap();
                }
                Err(e) => println!("watch error: {:?}", e),
            }
        }
    });

    Ok(())
}
// 前端监听示例
import { listen } from '@tauri-apps/api/event';
import { invoke } from '@tauri-apps/api/tauri';

async function setupFileWatcher() {
    // 启动文件监控
    await invoke('watch_directory', {
        path: './watched_folder',
    });

    // 监听文件变化事件
    await listen('file-change', (event) => {
        console.log('File changed:', event.payload);
    });
}

Channels 示例​

实时日志流示例：

src-tauri/src/main.rs
use tokio::sync::mpsc;
use std::collections::HashMap;
use std::sync::Mutex;

struct LogChannel(Mutex<HashMap<String, mpsc::Sender<String>>>);

#[tauri::command]
async fn start_log_stream(
    channel_id: String,
    state: tauri::State<'_, LogChannel>,
    window: tauri::Window,
) -> Result<(), String> {
    let (tx, mut rx) = mpsc::channel(100);
    state.0.lock().unwrap().insert(channel_id.clone(), tx);

    tauri::async_runtime::spawn(async move {
        while let Some(log) = rx.recv().await {
            window
                .emit(&format!("log:{}", channel_id), log)
                .unwrap();
        }
    });

    Ok(())
}
// 前端实现
import { listen } from '@tauri-apps/api/event';
import { invoke } from '@tauri-apps/api/tauri';

async function setupLogStream() {
    const channelId = 'app-logs';

    // 创建日志流通道
    await invoke('start_log_stream', { channelId });

    // 监听日志消息
    await listen(`log:${channelId}`, (event) => {
        console.log('New log:', event.payload);
    });
}

权限配置示例​

{
    "tauri": {
        "security": {
            "capabilities": [
                {
                    "identifier": "file-access",
                    "description": "允许读写文件",
                    "windows": ["main"],
                    "permissions": ["fs:default"]
                },
                {
                    "identifier": "log-stream",
                    "description": "允许访问日志流",
                    "windows": ["main"],
                    "permissions": ["event:default"]
                }
            ]
        }
    }
}

错误处理​

src-tauri/src/lib.rs
#[derive(Debug, thiserror::Error)]
enum Error {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
    #[error("Invalid input: {0}")]
    InvalidInput(String),
}

impl serde::Serialize for Error {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_str(self.to_string().as_str())
    }
}

#[tauri::command]
async fn handle_with_error() -> Result<String, Error> {
    // 业务逻辑
    Ok("Success".to_string())
}
// 前端错误处理
import { invoke } from '@tauri-apps/api/tauri';

try {
    await invoke('handle_with_error');
} catch (error) {
    console.error('Operation failed:', error);
}

最佳实践与安全性​

  1. 权限控制

    • 始终使用最小权限原则
    • 明确定义每个命令的权限需求
    • 使用 allowlist 限制可用 API

  2. 数据验证

    • 在前后端都进行数据验证
    • 使用强类型定义接口
    • 处理所有可能的错误情况

  3. 性能优化

    • 使用适当的通信方式
    • 避免频繁的小数据传输
    • 合理使用异步操作

性能优化​

  1. 批量处理

    • 合并多个小请求
    • 使用数据缓存
    • 实现请求队列

  2. 数据压缩

    • 大数据传输时使用压缩
    • 选择适当的序列化格式

  3. 异步处理

    • 使用异步命令
    • 实现后台任务
    • 合理使用线程池

实际案例​

  1. 文件管理器

    • 使用 Commands 处理文件操作
    • 使用 Events 监控文件变化
    • 使用 Channels 传输大文件

  2. 实时聊天应用

    • 使用 Channels 处理消息流
    • 使用 Events 处理状态更新
    • 使用 Commands 处理用户操作

总结​

Tauri 提供了丰富的前后端通信机制，每种方式都有其特定的使用场景：

  • Commands 适合一次性的请求-响应模式
  • Events 适合单向的状态通知
  • Channels 适合持续的双向数据交换

选择合适的通信方式对应用的性能和用户体验至关重要。同时，始终要注意安全性，合理使用权限控制和数据验证。

参考资源​

中年老码农,专注于自由职业与远程全栈开发
新文
使用 Combine 与 SwiftUI 构建用户注册表单：从零开始的表单验证与 MVVM 实践使用 Combine 和 `@EnvironmentObject` 实现数据共享SwiftUI Form 教程：使用 Picker、Toggle 和 Stepper 构建表单SwiftUI 模态框详解：Modal View、悬浮按钮与 Alert 全面解析SwiftUI 导航栏详解：从 NavigationView 到 NavigationStack 的自定义与进阶