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

添加新功能快速参考

🚀 快速步骤

1. 定义 Models     → src/models/new_feature.rs
2. 实现 Utils     → src/utils/new_algorithm.rs (可选)
3. 定义 Platform  → src/platforms/new_feature.rs
4. 实现平台代码   → src/platforms/windows/new_feature_impl.rs
5. 实现 Service   → src/services/new_feature_service.rs
6. 创建 Command   → src/commands/new_feature_commands.rs
7. 注册模块       → 更新 mod.rs 和 lib.rs
8. 测试验证       → 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())
}

4. Platform Trait 模板

// src/platforms/feature.rs
use crate::error::AppResult;

/// Trait 说明
pub trait FeatureAccessor {
    fn do_something(&self, param: &str) -> AppResult<String>;
}

#[cfg(windows)]
pub type PlatformFeature = crate::platforms::windows::feature_impl::WindowsFeature;

#[cfg(not(windows))]
pub type PlatformFeature = crate::platforms::windows::feature_impl::DummyFeature;

✅ 代码规范清单

命名规范

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

文档规范

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

代码规范

• 使用 AppResult<T> 返回
• 使用中文错误消息
• 参数验证在 Service 层
• Command 层简洁（仅适配）
• 使用 #[cfg(windows)] 条件编译

🔧 常用命令

# 格式化代码
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()
platforms/screen.rs          → ScreenAccessor trait
platforms/windows/screen_impl.rs → WindowsScreen
services/color_service.rs    → ColorService
commands/color_commands.rs   → pick_color_interactive
lib.rs                       → 注册命令

添加类似功能：截图

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

⚠️ 常见错误

错误 1: Trait 方法未找到

// ❌ 错误
use crate::platforms::screen::PlatformScreen;
PlatformScreen::get_pixel_color(x, y)?; // 找不到方法

// ✅ 正确
use crate::platforms::screen::PlatformScreen;
use crate::platforms::screen::ScreenAccessor; // 导入 trait
PlatformScreen::get_pixel_color(x, y)?;

错误 2: 类型不匹配

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

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

错误 3: 忘记注册命令

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

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

📚 相关文档

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