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

```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())
}
```

## ✅ 代码规范清单

### 命名规范

#### Rust 内部命名
- [ ] 模块文件: `snake_case`
- [ ] 结构体: `PascalCase`
- [ ] 函数: `snake_case`
- [ ] Trait: `PascalCase` + 能力描述（可选）

#### 跨语言命名（Rust ↔ TypeScript）
- [ ] 与前端交互的 struct 添加 `#[serde(rename_all = "camelCase")]`
- [ ] Rust 端使用 `snake_case` 命名字段
- [ ] 前端使用 `camelCase` 命名属性
- [ ] 类型名称两端保持 `PascalCase` 一致

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

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

### 文档规范
- [ ] 所有公开 API 有 `///` 注释
- [ ] 所有模块有 `//!` 注释
- [ ] 包含参数说明
- [ ] 包含返回值说明
- [ ] 包含错误说明
- [ ] 包含使用示例

### 代码规范
- [ ] 使用 `AppResult<T>` 返回
- [ ] 使用中文错误消息
- [ ] 参数验证在 Service 层
- [ ] Command 层简洁（仅适配）
- [ ] Service 层可直接调用 Windows API

## 🔧 常用命令

```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()
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: 类型不匹配
```rust
// ❌ 错误
pub fn toggle_window(window: &WebviewWindow) { }

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

### 错误 2: 忘记注册命令
```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 框架文档