164 lines
4.2 KiB
Markdown
164 lines
4.2 KiB
Markdown
# Data Transfer
|
||
|
||
一个用于自动化处理工作中繁琐任务的命令行工具。
|
||
|
||
## 项目简介
|
||
|
||
Data Transfer 是一个基于 Rust 开发的命令行程序，旨在帮助快速处理工作中所需执行的重复性、繁琐任务。通过模块化设计和良好的错误处理机制，该工具提供了可靠且易于扩展的任务自动化解决方案。
|
||
|
||
## 特性
|
||
|
||
- 🚀 **高性能**: 基于 Rust 构建，执行速度快，内存安全
|
||
- 🔧 **模块化设计**: 清晰的代码结构，易于维护和扩展
|
||
- ⚡ **命令行友好**: 使用 clap 提供完善的命令行参数解析
|
||
- 🛡️ **健壮的错误处理**: 使用 anyhow 和 thiserror 进行显式错误管理
|
||
- 📝 **详细的日志**: 支持 verbose 模式查看详细运行信息
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
data-transfer/
|
||
├── Cargo.toml # 项目配置和依赖管理
|
||
├── README.md # 项目文档
|
||
├── PROJECT_MILESTONES.md # 版本里程碑和依赖管理
|
||
└── src/
|
||
├── main.rs # 程序入口
|
||
├── cli.rs # 命令行参数定义
|
||
├── config.rs # 配置管理
|
||
├── error.rs # 错误类型定义
|
||
└── commands/ # 命令实现模块
|
||
├── mod.rs # 命令模块导出
|
||
└── example.rs # 示例命令实现
|
||
```
|
||
|
||
## 技术架构
|
||
|
||
### 核心模块
|
||
|
||
- **cli**: 使用 clap 的派生 API 定义命令行接口
|
||
- **config**: 管理应用程序配置和参数
|
||
- **error**: 自定义错误类型，提供清晰的错误上下文
|
||
- **commands**: 所有子命令的实现逻辑
|
||
|
||
### 设计原则
|
||
|
||
项目严格遵循以下 Rust 最佳实践：
|
||
|
||
1. **高内聚、低耦合**: 功能模块独立，接口清晰
|
||
2. **显式错误处理**: 使用 `Result<T, E>` 处理可恢复错误
|
||
3. **所有权管理**: 合理使用借用和生命周期
|
||
4. **并发安全**: 使用标准库同步原语保证线程安全
|
||
5. **测试驱动**: 为核心逻辑提供单元测试
|
||
|
||
## 安装
|
||
|
||
### 前置要求
|
||
|
||
- Rust 1.70 或更高版本
|
||
- Cargo
|
||
|
||
### 从源码构建
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone <repository-url>
|
||
cd data-transfer
|
||
|
||
# 构建项目
|
||
cargo build --release
|
||
|
||
# 可执行文件位于 target/release/data-transfer
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 基本命令
|
||
|
||
```bash
|
||
# 查看帮助信息
|
||
./data-transfer --help
|
||
|
||
# 启用详细日志模式
|
||
./data-transfer --verbose
|
||
|
||
# 运行示例命令
|
||
./data-transfer example --input "test data"
|
||
```
|
||
|
||
### 命令参数
|
||
|
||
- `-v, --verbose`: 启用详细日志输出
|
||
- `-h, --help`: 显示帮助信息
|
||
- `-V, --version`: 显示版本信息
|
||
|
||
## 开发指南
|
||
|
||
### 添加新命令
|
||
|
||
1. 在 `src/commands/` 目录下创建新模块文件
|
||
2. 在 `src/cli.rs` 中的 `Commands` 枚举添加新命令变体
|
||
3. 在 `src/commands/mod.rs` 中导出新命令
|
||
4. 在 `src/main.rs` 中处理新命令的执行逻辑
|
||
5. 为新命令编写单元测试
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
cargo test
|
||
|
||
# 运行特定测试
|
||
cargo test test_name
|
||
|
||
# 显示测试输出
|
||
cargo test -- --nocapture
|
||
```
|
||
|
||
### 代码规范
|
||
|
||
- 使用 `snake_case` 命名函数、变量和模块
|
||
- 使用 `UpperCamelCase` 命名类型（struct、enum、trait）
|
||
- 所有公共 API 必须包含文档注释（`///`）
|
||
- 禁止在生产代码中使用 `unwrap()` 或 `expect()`
|
||
- 优先使用不可变引用 `&`，仅在必要时使用 `&mut`
|
||
|
||
### 错误处理规范
|
||
|
||
- 可恢复错误使用 `Result<T, E>` 类型
|
||
- 使用 `?` 操作符传播错误
|
||
- 自定义错误类型继承 `thiserror::Error`
|
||
- 错误消息必须包含足够的上下文信息
|
||
|
||
## 依赖说明
|
||
|
||
核心依赖库：
|
||
|
||
- **clap**: 命令行参数解析库，提供强大的 CLI 构建能力
|
||
- **anyhow**: 简化错误处理和传播
|
||
- **thiserror**: 自定义错误类型的派生宏
|
||
|
||
详细依赖信息请参考 `PROJECT_MILESTONES.md`。
|
||
|
||
## 许可证
|
||
|
||
[待补充]
|
||
|
||
## 贡献指南
|
||
|
||
欢迎贡献代码和提交问题报告！请确保：
|
||
|
||
1. 代码符合项目规范
|
||
2. 添加必要的测试
|
||
3. 更新相关文档
|
||
4. 提交前运行 `cargo fmt` 和 `cargo clippy`
|
||
|
||
## 路线图
|
||
|
||
当前版本为 0.1.0，处于初始开发阶段。后续功能将根据实际需求逐步添加。
|
||
|
||
详细的版本规划和功能列表请查看 `PROJECT_MILESTONES.md`。
|
||
|
||
## 联系方式
|
||
|
||
[待补充]
|