tauri-shadcn-vite-project/docs/快速参考.md

添加新功能快速参考

🚀 快速步骤

1. 定义 Models     → src/models/new_feature.rs
2. 实现 Utils     → src/utils/new_algorithm.rs (可选)
3. 实现 Service   → src/services/new_feature_service.rs
4. 创建 Command   → src/commands/new_feature_commands.rs
5. 注册模块       → 更新 mod.rs 和 lib.rs
6. 测试验证       → cargo check && cargo test

📁 文件模板

1. Model 模板

// src/models/feature.rs
use serde::{Deserialize, Serialize};

/// 数据说明
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FeatureData {
    /// 字段说明
    pub field: String,
}

2. Service 模板

// src/services/feature_service.rs
//! 功能说明

use crate::error::AppResult;
use crate::models::feature::FeatureData;

/// 功能服务
pub struct FeatureService;

impl FeatureService {
    /// 功能说明
    pub fn execute(&self, input: &FeatureData) -> AppResult<Output> {
        // 实现
    }
}

3. Command 模板

// src/commands/feature_commands.rs
//! 命令说明

use crate::models::feature::FeatureData;

/// 命令说明
#[tauri::command]
pub fn execute_feature(input: FeatureData) -> Result<Output, String> {
    FeatureService::execute(&input).map_err(|e| e.to_string())
}

✅ 代码规范清单

命名规范

Rust 内部命名

• 模块文件: snake_case
• 结构体: PascalCase
• 函数: snake_case
• Trait: PascalCase + 能力描述（可选）

跨语言命名（Rust ↔ TypeScript）

• 与前端交互的 struct 添加 #[serde(rename_all = "camelCase")]
• Rust 端使用 snake_case 命名字段
• 前端使用 camelCase 命名属性
• 类型名称两端保持 PascalCase 一致

快速模板：

// Rust 端 - 必须添加 serde 注解
#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]  // ← 必须添加
pub struct MyConfig {
    pub field_name: String,  // snake_case
    pub user_id: u32,        // 自动转换为 userId
}

// 前端 - 使用 camelCase
export interface MyConfig {
    fieldName: string;  // camelCase
    userId: number;     // 与 Rust 端对应
}

文档规范

• 所有公开 API 有 /// 注释
• 所有模块有 //! 注释
• 包含参数说明
• 包含返回值说明
• 包含错误说明
• 包含使用示例

代码规范

• 使用 AppResult<T> 返回
• 使用中文错误消息
• 参数验证在 Service 层
• Command 层简洁（仅适配）
• Service 层可直接调用 Windows API

🔧 常用命令

# 格式化代码
cargo fmt

# 检查代码
cargo check

# 代码检查
cargo clippy

# 运行测试
cargo test

# 构建应用
pnpm build

# 开发运行
pnpm tauri dev

# 生成文档
cargo doc --open

📋 检查清单

提交前检查：

• cargo fmt 通过
• cargo clippy 无警告
• cargo test 全部通过
• cargo check 编译成功
• 文档注释完整
• 错误消息中文化
• 命令已注册

🎯 示例对照

参考：颜色取色功能

models/color.rs              → ColorInfo, RgbInfo, HslInfo
utils/color_conversion.rs    → rgb_to_hsl()
services/color_service.rs    → ColorService
commands/color_commands.rs   → pick_color_interactive
lib.rs                       → 注册命令

添加类似功能：截图

models/screenshot.rs         → ScreenshotConfig, ScreenshotResult
utils/image_utils.rs         → (可选) 图像处理工具
services/screenshot_service.rs → ScreenshotService
commands/screenshot_commands.rs → capture_screen
lib.rs                       → 注册 capture_screen

⚠️ 常见错误

错误 1: 类型不匹配

// ❌ 错误
pub fn toggle_window(window: &WebviewWindow) { }

// ✅ 正确
pub fn toggle_window(window: &Window) { }

错误 2: 忘记注册命令

// ❌ 错误：命令未注册，前端无法调用

// ✅ 正确：在 lib.rs 中注册
.invoke_handler(tauri::generate_handler![
    commands::new_commands::new_command, // 添加这一行
])

📚 相关文档

• 完整开发指南 - 详细的开发规范和教程
• Rust 官方文档 - Rust 语言参考
• Tauri 官方文档 - Tauri 框架文档