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 模板

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

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

### 2. Service 模板

```rust
// 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 模板

```rust
// 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 模板

```rust
// 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)]` 条件编译

## 🔧 常用命令

```bash
# 格式化代码
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 方法未找到
```rust
// ❌ 错误
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: 类型不匹配
```rust
// ❌ 错误
pub fn toggle_window(window: &WebviewWindow) { }

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

### 错误 3: 忘记注册命令
```rust
// ❌ 错误：命令未注册，前端无法调用

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

## 📚 相关文档

- [完整开发指南](./开发指南.md) - 详细的开发规范和教程
- [Rust 官方文档](https://doc.rust-lang.org/) - Rust 语言参考
- [Tauri 官方文档](https://tauri.app/) - Tauri 框架文档