forked from imbytecat/fullstack-starter
imbytecat
4035fcb202
- 将构建输出文件名从 `server-` 更改为 `app-` 以匹配新的命名规范。 - 将 Sidecar 模式中的 Server 统一更名为 App，以准确反映其作为主业务逻辑载体的角色，并同步更新相关配置、文件命名、日志信息及代码注释。 - 更新允许执行的二进制文件为应用程序二进制文件。 - 将 Sidecar Server 相关的术语和日志信息统一更新为 Sidecar App，以准确反映实际启动的应用程序名称。 - 将外部二进制文件路径从 server 更改为 app
358 lines
9.3 KiB
Markdown
358 lines
9.3 KiB
Markdown
# AGENTS.md - Tauri Shell 项目开发指南
|
||
|
||
本文档为 AI 编程助手和开发者提供项目规范、构建命令和代码风格指南。
|
||
|
||
## 项目概览
|
||
|
||
- **项目类型**: Tauri v2 桌面应用（轻量级壳子）
|
||
- **后端**: Rust (Edition 2021)
|
||
- **架构**: Sidecar 模式 - Sidecar App 承载主要业务逻辑
|
||
- **设计理念**: Tauri 仅提供原生桌面能力（文件对话框、系统通知等），Web 逻辑全部由 Sidecar App 处理
|
||
- **开发模式**: 使用 localhost:3000（需手动启动开发服务器）
|
||
- **生产模式**: 自动启动 Sidecar 二进制
|
||
- **异步运行时**: Tokio
|
||
- **Rust 版本**: 1.92.0+
|
||
- **工具管理**: 使用 mise 管理 Rust 和 Tauri CLI 版本（见 `mise.toml`）
|
||
|
||
## 构建、测试、运行命令
|
||
|
||
### 开发运行
|
||
```bash
|
||
# 开发模式运行 (需要先启动开发服务器)
|
||
# 终端 1: 启动前端开发服务器
|
||
bun run dev
|
||
|
||
# 终端 2: 启动 Tauri 应用
|
||
tauri dev
|
||
|
||
# 或者使用单命令并行启动（需要配置 package.json）
|
||
bun run dev:tauri
|
||
```
|
||
|
||
**开发模式说明**：
|
||
- 开发模式下，Tauri 直接连接到 `localhost:3000`（不启动 sidecar 二进制）
|
||
- 需要手动运行 `bun run dev` 来启动开发服务器
|
||
- 支持热重载（HMR），无需重启 Tauri 应用
|
||
|
||
### 构建
|
||
```bash
|
||
# 开发构建 (debug mode)
|
||
cargo build
|
||
|
||
# 生产构建
|
||
cargo build --release
|
||
|
||
# Tauri 应用打包 (生成安装程序)
|
||
tauri build
|
||
```
|
||
|
||
### 代码检查
|
||
```bash
|
||
# 编译检查 (不生成二进制)
|
||
cargo check
|
||
|
||
# Clippy 代码质量检查
|
||
cargo clippy
|
||
|
||
# Clippy 严格模式 (所有警告视为错误)
|
||
cargo clippy -- -D warnings
|
||
|
||
# 代码格式化检查
|
||
cargo fmt -- --check
|
||
|
||
# 自动格式化代码
|
||
cargo fmt
|
||
```
|
||
|
||
### 测试
|
||
```bash
|
||
# 运行所有测试
|
||
cargo test
|
||
|
||
# 运行单个测试 (按名称过滤)
|
||
cargo test test_function_name
|
||
|
||
# 运行特定模块的测试
|
||
cargo test module_name::
|
||
|
||
# 显示测试输出 (包括 println!)
|
||
cargo test -- --nocapture
|
||
|
||
# 运行单个测试并显示输出
|
||
cargo test test_name -- --nocapture
|
||
```
|
||
|
||
### 清理
|
||
```bash
|
||
# 清理构建产物
|
||
cargo clean
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
app-desktop/
|
||
├── src/
|
||
│ ├── main.rs # 入口文件 (仅调用 lib::run)
|
||
│ ├── lib.rs # 核心应用逻辑 (注册插件、命令、状态)
|
||
│ ├── commands/
|
||
│ │ └── mod.rs # 原生桌面功能命令 (文件对话框、通知等)
|
||
│ └── sidecar.rs # Sidecar 进程管理 (启动、端口扫描、清理)
|
||
├── binaries/ # Sidecar 二进制文件
|
||
│ └── app-* # Sidecar App 可执行文件 (示例: app)
|
||
├── capabilities/ # Tauri v2 权限配置
|
||
│ └── default.json
|
||
├── icons/ # 应用图标资源
|
||
├── gen/schemas/ # 自动生成的 Schema (不要手动编辑)
|
||
├── Cargo.toml # Rust 项目配置
|
||
├── tauri.conf.json # Tauri 应用配置
|
||
├── build.rs # Rust 构建脚本
|
||
└── mise.toml # 开发工具版本管理
|
||
```
|
||
|
||
## Rust 代码风格指南
|
||
|
||
### 导入 (Imports)
|
||
|
||
- 使用标准库、外部 crate、当前 crate 的顺序，用空行分隔
|
||
- 按字母顺序排列
|
||
- 优先使用具体导入而非通配符 `*`
|
||
|
||
```rust
|
||
// ✅ 推荐
|
||
use std::sync::Mutex;
|
||
use std::time::Duration;
|
||
|
||
use tauri::Manager;
|
||
use tauri_plugin_shell::ShellExt;
|
||
use tauri_plugin_shell::process::{CommandEvent, CommandChild};
|
||
|
||
// ❌ 避免
|
||
use tauri::*;
|
||
```
|
||
|
||
### 命名规范
|
||
|
||
- **函数和变量**: `snake_case`
|
||
- **类型、结构体、枚举、Trait**: `PascalCase`
|
||
- **常量和静态变量**: `SCREAMING_SNAKE_CASE`
|
||
- **生命周期参数**: 简短小写字母，如 `'a`, `'b`
|
||
|
||
```rust
|
||
// ✅ 推荐
|
||
struct SidecarProcess(Mutex<Option<CommandChild>>);
|
||
const DEFAULT_PORT: u16 = 3000;
|
||
async fn find_available_port(start: u16) -> u16 { }
|
||
|
||
// ❌ 避免
|
||
struct sidecar_process { }
|
||
const defaultPort: u16 = 3000;
|
||
```
|
||
|
||
### 类型注解
|
||
|
||
- 函数参数必须有类型注解
|
||
- 函数返回值必须明确声明 (除非返回 `()`)
|
||
- 优先使用具体类型而非 `impl Trait` (除非必要)
|
||
- 使用 `&str` 而非 `String` 作为只读字符串参数
|
||
|
||
```rust
|
||
// ✅ 推荐
|
||
#[tauri::command]
|
||
fn greet(name: &str) -> String {
|
||
format!("Hello, {}!", name)
|
||
}
|
||
|
||
async fn is_port_available(port: u16) -> bool {
|
||
tokio::net::TcpListener::bind(format!("127.0.0.1:{}", port))
|
||
.await
|
||
.is_ok()
|
||
}
|
||
```
|
||
|
||
### 错误处理
|
||
|
||
- 使用 `Result<T, E>` 返回可能失败的操作
|
||
- 使用 `expect()` 时提供有意义的错误消息 (中文)
|
||
- 避免 `unwrap()` 在生产代码中，除非逻辑上保证不会 panic
|
||
- 使用 `?` 操作符传播错误
|
||
- 记录关键错误信息到控制台
|
||
|
||
```rust
|
||
// ✅ 推荐
|
||
let sidecar = app_handle
|
||
.shell()
|
||
.sidecar("app")
|
||
.expect("无法找到 app sidecar");
|
||
|
||
let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");
|
||
|
||
// 日志记录
|
||
eprintln!("✗ Sidecar App 启动失败");
|
||
println!("✓ Sidecar App 启动成功！");
|
||
|
||
// ❌ 避免
|
||
let data = read_file().unwrap(); // 无上下文信息
|
||
```
|
||
|
||
### 异步代码
|
||
|
||
- 使用 `async/await` 而非手动创建 Future
|
||
- Tauri 内部使用 `tauri::async_runtime::spawn` 启动异步任务
|
||
- 使用 Tokio 的异步 API (如 `tokio::net::TcpListener`)
|
||
- 避免阻塞异步运行时 (使用 `tokio::task::spawn_blocking`)
|
||
|
||
```rust
|
||
// ✅ 推荐
|
||
tauri::async_runtime::spawn(async move {
|
||
let port = find_available_port(3000).await;
|
||
// ...
|
||
});
|
||
```
|
||
|
||
### 格式化
|
||
|
||
- 使用 `cargo fmt` 自动格式化
|
||
- 缩进: 4 空格
|
||
- 行宽: 100 字符 (rustfmt 默认)
|
||
- 结构体和枚举的字段每行一个 (如果超过一定长度)
|
||
- 链式调用适当换行提高可读性
|
||
|
||
### 注释
|
||
|
||
- 使用中文注释说明复杂逻辑
|
||
- 代码块前添加简短说明注释
|
||
- 避免显而易见的注释
|
||
|
||
```rust
|
||
// ✅ 推荐
|
||
// 全局状态：存储 Sidecar App 进程句柄
|
||
struct SidecarProcess(Mutex<Option<CommandChild>>);
|
||
|
||
// 检查端口是否可用
|
||
async fn is_port_available(port: u16) -> bool { }
|
||
```
|
||
|
||
## Tauri 特定规范
|
||
|
||
### 模块组织
|
||
|
||
- **`lib.rs`**: 主入口，负责注册插件、命令、状态管理
|
||
- **`commands/mod.rs`**: 所有 Tauri 命令集中定义，命令必须是 `pub fn`
|
||
- **`sidecar.rs`**: Sidecar 进程管理逻辑，导出公共 API（`spawn_sidecar`, `cleanup_sidecar_process`）
|
||
|
||
```rust
|
||
// lib.rs - 模块声明
|
||
mod commands;
|
||
mod sidecar;
|
||
|
||
use sidecar::SidecarProcess;
|
||
|
||
// 注册命令时使用模块路径
|
||
.invoke_handler(tauri::generate_handler![commands::greet])
|
||
```
|
||
|
||
### 命令定义
|
||
|
||
- 使用 `#[tauri::command]` 宏标记命令
|
||
- 命令函数必须是公开的或在 `invoke_handler` 中注册
|
||
- 参数类型必须实现 `serde::Deserialize`
|
||
- 返回类型必须实现 `serde::Serialize`
|
||
|
||
```rust
|
||
#[tauri::command]
|
||
fn greet(name: &str) -> String {
|
||
format!("Hello, {}!", name)
|
||
}
|
||
|
||
// 在 Builder 中注册
|
||
.invoke_handler(tauri::generate_handler![greet])
|
||
```
|
||
|
||
### 状态管理
|
||
|
||
- 使用 `app.manage()` 注册全局状态
|
||
- 状态必须实现 `Send + Sync`
|
||
- 使用 `Mutex` 或 `RwLock` 保证线程安全
|
||
|
||
```rust
|
||
struct SidecarProcess(Mutex<Option<CommandChild>>);
|
||
|
||
// 注册状态
|
||
app.manage(SidecarProcess(Mutex::new(None)));
|
||
|
||
// 访问状态
|
||
if let Some(state) = app_handle.try_state::<SidecarProcess>() {
|
||
*state.0.lock().unwrap() = Some(child);
|
||
}
|
||
```
|
||
|
||
### Sidecar 进程管理
|
||
|
||
- Sidecar 二进制必须在 `tauri.conf.json` 的 `bundle.externalBin` 中声明
|
||
- 使用 `app.shell().sidecar()` 启动 sidecar
|
||
- 在应用退出时清理子进程 (监听 `RunEvent::ExitRequested`)
|
||
|
||
```rust
|
||
// 启动 sidecar
|
||
let sidecar = app_handle
|
||
.shell()
|
||
.sidecar("app")
|
||
.expect("无法找到 app sidecar")
|
||
.env("PORT", port.to_string());
|
||
|
||
// 清理进程
|
||
match event {
|
||
tauri::RunEvent::ExitRequested { .. } | tauri::RunEvent::Exit => {
|
||
if let Some(child) = process.take() {
|
||
let _ = child.kill();
|
||
}
|
||
}
|
||
_ => {}
|
||
}
|
||
```
|
||
|
||
## 依赖管理
|
||
|
||
- 在 `Cargo.toml` 中明确声明依赖版本
|
||
- 使用语义化版本 (如 `"2"` 表示兼容 2.x.x)
|
||
- 仅启用需要的 feature 以减少编译时间和二进制大小
|
||
|
||
```toml
|
||
tauri = { version = "2", features = [] }
|
||
tauri-plugin-opener = "2"
|
||
tauri-plugin-shell = "2"
|
||
serde = { version = "1", features = ["derive"] }
|
||
tokio = { version = "1", features = ["net"] }
|
||
```
|
||
|
||
## 开发工具
|
||
|
||
推荐安装以下 VSCode 扩展:
|
||
- `tauri-apps.tauri-vscode` - Tauri 官方支持
|
||
- `rust-lang.rust-analyzer` - Rust 语言服务器
|
||
|
||
## 最佳实践
|
||
|
||
1. **开发环境配置**:
|
||
- 开发模式下需先启动前端开发服务器（`bun run dev`），再启动 Tauri（`tauri dev`）
|
||
- 生产构建自动打包 sidecar 二进制，无需额外配置
|
||
2. **进程生命周期**: 始终在应用退出时清理子进程和资源
|
||
3. **端口管理**:
|
||
- 开发模式固定使用 3000 端口（与开发服务器匹配）
|
||
- 生产模式使用端口扫描避免硬编码端口冲突
|
||
4. **超时处理**: 异步操作设置合理的超时时间 (如 5 秒)
|
||
5. **日志**: 使用表情符号 (✓/✗/🔧/🚀) 和中文消息提供清晰的状态反馈
|
||
6. **错误退出**: 关键错误时调用 `std::process::exit(1)`
|
||
7. **窗口配置**: 使用 `WebviewWindowBuilder` 动态创建窗口
|
||
|
||
## 提交代码前检查清单
|
||
|
||
- [ ] `cargo fmt` 格式化通过
|
||
- [ ] `cargo clippy` 无警告
|
||
- [ ] `cargo check` 编译通过
|
||
- [ ] `cargo test` 测试通过
|
||
- [ ] 更新相关注释和文档
|
||
- [ ] 检查是否有 `unwrap()` 需要替换为 `expect()`
|
||
- [ ] 验证 Tauri 应用正常启动和退出
|