Rust 命令行待办工具

禁默

发布于 2025-12-24 15:33:44

Rust项目实战- 命令行待办工具全解析

一、项目概述

1.1 项目背景

Rust 兼具内存安全与高性能。本项目借助 Rust 开发命令行待办工具，既利用 Rust 的性能优势，又通过合理设计满足日常待办管理需求，后续还新增优先级管理与关键词搜索功能，进一步提升工具实用性。

1.2 核心功能

基础功能：添加、查看、标记完成、删除待办，数据以 JSON 格式存储在本地 todo.json 文件，实现持久化，重启工具数据不丢失。
新增功能：
- 优先级管理：支持 Low/Medium/High 三种优先级，添加待办可指定优先级，查看待办按优先级降序排序。
- 关键词搜索：新增搜索命令，按关键词筛选待办内容，搜索不区分大小写，结果按优先级排序显示。

1.3 技术栈

基础语法：变量、函数、结构体、枚举、循环、条件判断。
第三方库：
- clap：解析命令行参数，支持子命令与可选参数配置。
- serde + serde_json：实现 JSON 数据的序列化与反序列化，用于待办数据的读写。
- chrono：处理时间，记录待办创建时间，支持时间格式转换。
标准库：文件 IO（std::fs）用于读写本地文件，std::path 处理文件路径，错误处理（Result 类型）处理各类异常情况。

二、环境准备

2.1 安装依赖工具

工具	版本要求	安装方法	验证命令

Rust 工具链	1.70+	官网下载 rustup-init，默认安装	rustc --version

三、项目初始化与配置

3.1 创建项目

打开终端，执行以下命令创建 Rust 项目：

cargo new rust_todo_cli
cd rust_todo_cli

生成的初始目录结构如下：

rust_todo_cli/
├─ src/
│  └─ main.rs    # 主程序文件，处理命令行交互逻辑
└─ Cargo.toml    # 项目配置文件，管理依赖与项目信息

3.2 配置依赖

修改 Cargo.toml 文件，在 [dependencies] 下添加所需第三方库依赖：

[package]
name = "rust_todo_cli"
version = "0.1.0"
edition = "2021"

[dependencies]
# 命令行参数解析（支持子命令与参数配置）
clap = { version = "4.0", features = ["derive"] }
# JSON 序列化/反序列化（处理待办数据存储）
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
# 时间处理（记录待办创建时间）
chrono = { version = "0.4", features = ["serde", "std"] }

3.3 模块导出配置

新建 src/lib.rs 文件，用于导出自定义模块，方便 main.rs 调用：

// src/lib.rs
pub mod todo; // 导出 todo 模块，包含待办数据结构与核心操作

四、核心代码实现

4.1 待办数据结构与核心操作（src/todo.rs）

use chrono::{DateTime, Local, Utc};
use serde::{Deserialize, Serialize};
use std::fmt;
use std::fs;
use std::path::Path;
use std::str::FromStr;

// 待办优先级枚举（支持排序、序列化、命令行参数解析）
#[derive(Debug, Serialize, Deserialize, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Priority {
    Low,    // 低优先级
    Medium, // 中优先级（默认）
    High,   // 高优先级
}

// 待办任务状态：未完成/已完成
#[derive(Debug, Serialize, Deserialize, Clone, Copy)]
pub enum TodoStatus {
    Pending,   // 未完成
    Completed, // 已完成
}

// 待办任务结构体（包含优先级字段）
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct Todo {
    pub id: usize,                // 唯一序号（用于标记/删除）
    pub content: String,          // 任务内容
    pub created_at: DateTime<Utc>,// 创建时间（UTC 时间，避免时区问题）
    pub status: TodoStatus,       // 任务状态
    pub priority: Priority,       // 任务优先级
}

// 待办列表（封装待办的核心操作）
#[derive(Debug, Serialize, Deserialize)]
pub struct TodoList {
    pub todos: Vec<Todo>, // 存储所有待办
}

// 优先级相关方法（图标转换、文字描述、默认值、命令行解析）
impl Priority {
    // 优先级转图标（用于友好显示）
    pub fn to_icon(&self) -> &str {
        match self {
            Priority::Low => "🔵",
            Priority::Medium => "🟡",
            Priority::High => "🔴",
        }
    }

    // 优先级转文字描述（用于终端输出）
    pub fn to_str(&self) -> &str {
        match self {
            Priority::Low => "低",
            Priority::Medium => "中",
            Priority::High => "高",
        }
    }
}

// 实现 Display 特性（枚举转字符串，支持 clap 命令行参数显示）
impl fmt::Display for Priority {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Priority::Low => write!(f, "Low"),
            Priority::Medium => write!(f, "Medium"),
            Priority::High => write!(f, "High"),
        }
    }
}

// 实现 FromStr 特性（字符串转枚举，支持 clap 解析用户输入）
impl FromStr for Priority {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_lowercase().as_str() {
            "low" => Ok(Priority::Low),
            "medium" => Ok(Priority::Medium),
            "high" => Ok(Priority::High),
            _ => Err(format!(
                "无效的优先级：{}！仅支持 Low/Medium/High（不区分大小写）",
                s
            )),
        }
    }
}

// 为优先级实现默认值（默认中优先级）
impl Default for Priority {
    fn default() -> Self {
        Priority::Medium
    }
}

// 待办列表核心操作实现
impl TodoList {
    // 1. 从本地文件加载待办列表（文件不存在则返回空列表）
    pub fn load_from_file(file_path: &str) -> Result<Self, Box<dyn std::error::Error>> {
        if !Path::new(file_path).exists() {
            return Ok(Self { todos: Vec::new() });
        }
        let content = fs::read_to_string(file_path)?;
        let todo_list: Self = serde_json::from_str(&content)?;
        Ok(todo_list)
    }

    // 2. 保存待办列表到本地文件（JSON 格式，带缩进便于阅读）
    pub fn save_to_file(&self, file_path: &str) -> Result<(), Box<dyn std::error::Error>> {
        let content = serde_json::to_string_pretty(self)?;
        fs::write(file_path, content)?;
        Ok(())
    }

    // 3. 添加新待办（支持指定优先级，默认中优先级）
    pub fn add_todo(&mut self, content: String, priority: Priority) {
        let new_id = self.todos.last().map(|t| t.id + 1).unwrap_or(1);
        let new_todo = Todo {
            id: new_id,
            content,
            created_at: Utc::now(),
            status: TodoStatus::Pending,
            priority,
        };
        self.todos.push(new_todo);
    }

    // 4. 标记待办为已完成（通过 ID 查找，未找到则返回错误）
    pub fn complete_todo(&mut self, todo_id: usize) -> Result<(), String> {
        let todo = self
            .todos
            .iter_mut()
            .find(|t| t.id == todo_id)
            .ok_or_else(|| format!("未找到 ID 为 {} 的待办", todo_id))?;
        todo.status = TodoStatus::Completed;
        Ok(())
    }

    // 5. 删除待办（通过 ID 筛选，未找到则返回错误）
    pub fn delete_todo(&mut self, todo_id: usize) -> Result<(), String> {
        let initial_len = self.todos.len();
        self.todos.retain(|t| t.id != todo_id);
        if self.todos.len() == initial_len {
            return Err(format!("未找到 ID 为 {} 的待办", todo_id));
        }
        Ok(())
    }

    // 6. 显示所有待办（按优先级降序排序，含状态、优先级、时间信息）
    pub fn display(&self) {
        if self.todos.is_empty() {
            println!("🎉 暂无待办任务，快去添加一个吧！");
            return;
        }

        let mut sorted_todos = self.todos.clone();
        // 按优先级降序排序（High > Medium > Low）
        sorted_todos.sort_by(|a, b| b.priority.cmp(&a.priority));

        println!("📋 你的待办列表（共 {} 个任务，按优先级排序）：", sorted_todos.len());
        for todo in sorted_todos {
            let status_icon = match todo.status {
                TodoStatus::Pending => "🔴",
                TodoStatus::Completed => "🟢",
            };
            let priority_icon = todo.priority.to_icon();
            let priority_str = todo.priority.to_str();
            // UTC 时间转本地时间
            let local_time = todo.created_at.with_timezone(&Local);
            let time_str = local_time.format("%Y-%m-%d %H:%M:%S").to_string();

            println!(
                "{} {} ID: {} | 内容: {} | 优先级: {} | 创建时间: {}",
                status_icon, priority_icon, todo.id, todo.content, priority_str, time_str
            );
        }
    }

    // 7. 关键词搜索待办（不区分大小写，返回匹配结果）
    pub fn search(&self, keyword: &str) -> Vec<Todo> {
        let lower_keyword = keyword.to_lowercase();
        self.todos
            .iter()
            .filter(|todo| todo.content.to_lowercase().contains(&lower_keyword))
            .cloned()
            .collect()
    }

    // 8. 显示搜索结果（按优先级排序，空结果提示友好信息）
    pub fn display_search_results(&self, keyword: &str) {
        let results = self.search(keyword);
        if results.is_empty() {
            println!("🔍 未找到包含关键词「{}」的待办任务", keyword);
            return;
        }

        let mut sorted_results = results;
        sorted_results.sort_by(|a, b| b.priority.cmp(&a.priority));

        println!(
            "🔍 找到 {} 个包含关键词「{}」的待办任务：",
            sorted_results.len(),
            keyword
        );
        for todo in sorted_results {
            let status_icon = match todo.status {
                TodoStatus::Pending => "🔴",
                TodoStatus::Completed => "🟢",
            };
            let priority_icon = todo.priority.to_icon();
            let priority_str = todo.priority.to_str();
            let local_time = todo.created_at.with_timezone(&Local);
            let time_str = local_time.format("%Y-%m-%d %H:%M:%S").to_string();

            println!(
                "{} {} ID: {} | 内容: {} | 优先级: {} | 创建时间: {}",
                status_icon, priority_icon, todo.id, todo.content, priority_str, time_str
            );
        }
    }
}

4.2 命令行交互逻辑（src/main.rs）

use clap::Parser;
use rust_todo_cli::todo::{Priority, TodoList};

// 定义命令行参数结构（支持 add/list/complete/delete/search 子命令）
#[derive(Parser, Debug)]
#[command(author, version, about = "Rust 命令行待办工具（支持优先级+搜索）", long_about = None)]
enum TodoCommand {
    /// 添加新待办（示例：todo add "买牛奶" -p High）
    Add {
        /// 待办任务内容
        content: String,

        /// 任务优先级（可选，默认 Medium）
        #[arg(short = 'p', long = "priority", default_value_t = Priority::Medium)]
        priority: Priority,
    },

    /// 查看所有待办（按优先级排序）
    List,

    /// 标记待办为已完成（示例：todo complete 1）
    Complete {
        /// 待办ID
        id: usize,
    },

    /// 删除待办（示例：todo delete 1）
    Delete {
        /// 待办ID
        id: usize,
    },

    /// 搜索待办（示例：todo search "Rust"）
    Search {
        /// 搜索关键词（不区分大小写）
        keyword: String,
    },
}

// 本地待办数据存储路径（当前目录下的 todo.json）
const TODO_FILE_PATH: &str = "todo.json";

fn main() {
    // 解析命令行参数
    let command = TodoCommand::parse();

    // 加载本地待办列表（处理加载错误）
    let mut todo_list = match TodoList::load_from_file(TODO_FILE_PATH) {
        Ok(list) => list,
        Err(e) => {
            eprintln!("❌ 加载待办列表失败：{}", e);
            return;
        }
    };

    // 根据不同命令执行对应操作
    match command {
        TodoCommand::Add { content, priority } => {
            todo_list.add_todo(content.clone(), priority);
            if todo_list.save_to_file(TODO_FILE_PATH).is_ok() {
                println!(
                    "✅ 成功添加待办：{} | 优先级：{}",
                    content, priority.to_str()
                );
            } else {
                eprintln!("❌ 保存待办失败，请重试！");
            }
        }

        TodoCommand::List => {
            todo_list.display();
        }

        TodoCommand::Complete { id } => {
            match todo_list.complete_todo(id) {
                Ok(_) => {
                    if todo_list.save_to_file(TODO_FILE_PATH).is_ok() {
                        println!("✅ 成功标记 ID {} 为已完成！", id);
                    } else {
                        eprintln!("❌ 保存状态失败，请重试！");
                    }
                }
                Err(e) => eprintln!("❌ 标记失败：{}", e),
            }
        }

        TodoCommand::Delete { id } => {
            match todo_list.delete_todo(id) {
                Ok(_) => {
                    if todo_list.save_to_file(TODO_FILE_PATH).is_ok() {
                        println!("✅ 成功删除 ID {} 的待办！", id);
                    } else {
                        eprintln!("❌ 保存删除结果失败，请重试！");
                    }
                }
                Err(e) => eprintln!("❌ 删除失败：{}", e),
            }
        }

        TodoCommand::Search { keyword } => {
            todo_list.display_search_results(&keyword);
        }
    }
}

五、项目运行与测试

5.1 基本命令格式

所有命令需在 rust_todo_cli 项目目录下执行，格式为 cargo run -- 子命令参数，各功能对应的命令如下：

功能	命令示例	说明
添加待办	cargo run -- add "买牛奶"	添加默认优先级（中）的待办
添加指定优先级待办	cargo run -- add "完成 Rust 项目" -p High	添加高优先级待办
查看待办	cargo run -- list	显示所有待办，按优先级降序排序
标记完成	cargo run -- complete 1	标记 ID 为 1 的待办为已完成
删除待办	cargo run -- delete 1	删除 ID 为 1 的待办
搜索待办	cargo run -- search "Rust"	搜索内容包含 “Rust” 的待办，不区分大小写

5.2 完整测试流程

步骤 1：添加不同优先级待办

# 添加高优先级待办
cargo run -- add "完成 Rust 命令行工具开发" -p High
# 添加中优先级待办（默认）
cargo run -- add "学习 Rust 序列化库 serde"
# 添加低优先级待办
cargo run -- add "整理项目文档" -p Low

执行后终端输出：

✅ 成功添加待办：完成 Rust 命令行工具开发 | 优先级：高
✅ 成功添加待办：学习 Rust 序列化库 serde | 优先级：中
✅ 成功添加待办：整理项目文档 | 优先级：低

步骤 2：查看待办列表（验证优先级排序）

执行查看命令：

cargo run -- list

输出结果（按优先级 High > Medium > Low 排序，含状态、优先级图标与时间）：

📋 你的待办列表（共 3 个任务，按优先级排序）：
🔴 🔴 ID: 1 | 内容: 完成 Rust 命令行工具开发 | 优先级: 高 | 创建时间: 2025-11-04 19:53:27
🔴 🟡 ID: 2 | 内容: 学习 Rust 序列化库 serde | 优先级: 中 | 创建时间: 2025-11-04 19:55:35
🔴 🔵 ID: 3 | 内容: 整理项目文档 | 优先级: 低 | 创建时间: 2025-11-04 19:55:45

说明：状态图标 “🔴” 表示未完成，优先级图标 “🔴/🟡/🔵” 对应高 / 中 / 低优先级，时间已转换为本地时区。

步骤 3：标记待办为已完成

执行标记命令（标记 ID=2 的待办）：

cargo run -- complete 2

输出结果：

✅ 成功标记 ID 2 为已完成！

再次查看待办（cargo run -- list），ID=2 的状态图标变为 “🟢”：

📋 你的待办列表（共 3 个任务，按优先级排序）：
🔴 🔴 ID: 1 | 内容: 完成 Rust 命令行工具开发 | 优先级: 高 | 创建时间: 2025-11-04 19:53:27
🟢 🟡 ID: 2 | 内容: 学习 Rust 序列化库 serde | 优先级: 中 | 创建时间: 2025-11-04 19:55:35
🔴 🔵 ID: 3 | 内容: 整理项目文档 | 优先级: 低 | 创建时间: 2025-11-04 19:55:45

步骤 4：测试搜索功能（不区分大小写）

场景 1：搜索包含 “Rust” 的待办

执行搜索命令：

cargo run -- search "Rust"

输出结果（匹配 ID=1 和 ID=2 的待办）：

🔍 找到 2 个包含关键词「Rust」的待办任务：
🔴 🔴 ID: 1 | 内容: 完成 Rust 命令行工具开发 | 优先级: 高 | 创建时间: 2025-11-04 19:53:27
🟢 🟡 ID: 2 | 内容: 学习 Rust 序列化库 serde | 优先级: 中 | 创建时间: 2025-11-04 19:55:35

场景 2：搜索小写关键词 “rust”（验证不区分大小写）

执行搜索命令：

cargo run -- search "rust"

输出结果与场景 1 一致，说明搜索不区分大小写。

场景 3：搜索不存在的关键词（如 “Java”）

执行搜索命令：

cargo run -- search "Java"

输出友好提示：

🔍 未找到包含关键词「Java」的待办任务

步骤 5：删除待办

执行删除命令（删除 ID=3 的低优先级待办）：

cargo run -- delete 3

输出结果：

✅ 成功删除 ID 3 的待办！

查看待办（cargo run -- list），ID=3 的待办已移除：

 你的待办列表（共 2 个任务，按优先级排序）：
🔴 🔴 ID: 1 | 内容: 完成 Rust 命令行工具开发 | 优先级: 高 | 创建时间: 2025-11-04 19:53:27
🟢 🟡 ID: 2 | 内容: 学习 Rust 序列化库 serde | 优先级: 中 | 创建时间: 2025-11-04 19:55:35

5.3 数据持久化验证

待办数据存储在项目根目录的 todo.json 文件中，打开文件可查看 JSON 格式的持久化数据（带缩进，便于人类阅读）：

{
  "todos": [
    {
      "id": 1,
      "content": "完成 Rust 命令行工具开发",
      "created_at": "2025-11-04T11:53:27.248706900Z",
      "status": "Pending",
      "priority": "High"
    },
    {
      "id": 2,
      "content": "学习 Rust 序列化库 serde",
      "created_at": "2025-11-04T11:55:35.909026300Z",
      "status": "Completed",
      "priority": "Medium"
    }
  ]
}

关键验证点：

重启终端或电脑后，重新执行 cargo run -- list，数据依然存在；
新增 / 删除 / 标记操作后，todo.json 会自动更新，确保数据与操作一致。

六、常见问题与解决方案

常见问题	原因分析	解决方案
执行 cargo run 报错 “找不到 todo 模块”	未创建 src/lib.rs 或未导出 todo 模块	确保 src/lib.rs 中存在 pub mod todo; 代码
添加待办时优先级参数不生效	优先级参数值拼写错误（如 --priority high 写成 --priority hight）	优先级参数仅支持 Low/Medium/High（不区分大小写），检查拼写是否正确
搜索结果为空但待办存在	关键词与待办内容完全不匹配，或存在特殊字符（如空格、符号）	简化关键词（如用 “Rust” 代替 “Rust 开发”），或检查待办内容是否包含目标关键词
todo.json 文件损坏导致加载失败	手动修改 todo.json 时格式错误（如缺少逗号、引号不匹配）	删除损坏的 todo.json 文件，重新添加待办（或从备份恢复正确的 JSON 格式）
终端显示乱码（如图标不显示）	终端不支持 Unicode 字符（如 Windows 旧版 CMD）	改用 Windows Terminal 或 PowerShell，或在 todo.rs 中替换图标为文字（如 “高” 代替 “🔴”）

七、项目总结

7.1 核心技术收获

Rust 语法实践：掌握结构体、枚举、 trait（如 Default/PartialOrd）、错误处理（Result 类型、? 操作符）的实际应用；
第三方库使用：熟悉 clap 命令行解析、serde JSON 序列化、chrono 时间处理的核心 API；
工程化思维：通过模块拆分（todo.rs 封装核心逻辑、main.rs 处理交互）实现代码解耦，通过 JSON 持久化确保数据安全。