Rust 项目实战经验：非科班转码，从零到一构建 CLI 工具的完整过程

Rust 项目实战经验：非科班转码，从零到一构建 CLI 工具的完整过程

一、非科班转码的真实困境：不是学不会，是不知道学什么

非科班转码最大的困难不是"Rust 太难"，而是"不知道该做什么项目来练手"。教程里的例子都是 println!("hello") 和 fibonacci(n)，但真实项目需要处理命令行参数、文件 IO、错误传播、模块拆分——这些在教程里一笔带过，却是工程实践的核心。

本文记录从零构建一个 CLI 文件搜索工具的完整过程：从需求分析到架构设计，从核心逻辑到错误处理，从单文件到模块拆分。这不是"完美代码示范"，而是"踩坑记录"——每个决策都记录了为什么这样做、踩了什么坑、怎么解决的。

二、项目架构：从需求到模块拆分

flowchart TB
    A[需求: 文件内容搜索工具] --> B[核心功能]
    B --> B1[递归目录遍历]
    B --> B2[文件内容匹配]
    B --> B3[结果高亮输出]

    B --> C[模块拆分]
    C --> C1[main.rs: 入口+参数解析]
    C --> C2[walker.rs: 目录遍历]
    C --> C3[searcher.rs: 内容搜索]
    C --> C4[output.rs: 结果格式化]

    C1 --> D[依赖: clap + anyhow]
    C2 --> E[依赖: walkdir + ignore]
    C3 --> F[依赖: regex]
    C4 --> G[依赖: colored]

    style B fill:#ff6b6b,color:#fff
    style C fill:#4d96ff,color:#fff

模块拆分的原则：

• main.rs 只做入口：解析参数、调用核心逻辑、处理顶层错误。业务逻辑全部在子模块中。
• 每个模块一个职责：walker 负责遍历、searcher 负责搜索、output 负责输出。模块间通过结构体传递数据，而非全局变量。
• 错误类型统一：所有模块的错误最终汇聚到 anyhow::Error，main 函数统一处理。

三、完整项目实现

# Cargo.toml
[package]
name = "qsearch"
version = "0.1.0"
edition = "2021"

[dependencies]
clap = { version = "4", features = ["derive"] }  # 命令行参数解析
anyhow = "1.0"                                     # 错误处理
walkdir = "2"                                       # 目录遍历
ignore = "0.4"                                      # .gitignore 感知的遍历
regex = "1"                                         # 正则搜索
colored = "2"                                       # 终端彩色输出

// src/main.rs — 入口文件
use anyhow::Result;
use clap::Parser;

mod walker;
mod searcher;
mod output;

/// 快速文件内容搜索工具
#[derive(Parser, Debug)]
#[command(name = "qsearch")]
#[command(about = "在文件中搜索匹配的内容")]
struct Args {
    /// 搜索模式（支持正则表达式）
    pattern: String,

    /// 搜索目录（默认当前目录）
    #[arg(default_value = ".")]
    path: String,

    /// 文件类型过滤（如 rs,py,txt）
    #[arg(short, long)]
    ext: Option<String>,

    /// 忽略 .gitignore 规则
    #[arg(long, default_value_t = false)]
    no_ignore: bool,

    /// 最大搜索深度
    #[arg(short, long, default_value_t = 10)]
    depth: usize,

    /// 只显示文件名，不显示匹配行
    #[arg(short, long, default_value_t = false)]
    files_only: bool,
}

fn main() -> Result<()> {
    let args = Args::parse();

    // 构建搜索配置
    let config = searcher::SearchConfig {
        pattern: regex::Regex::new(&args.pattern)?,
        ext_filter: args.ext,
        files_only: args.files_only,
    };

    // 遍历目录并搜索
    let walker = walker::FileWalker::new(
        &args.path,
        args.depth,
        !args.no_ignore,
    );

    let mut match_count = 0;
    let mut file_count = 0;

    for entry in walker {
        let entry = match entry {
            Ok(e) => e,
            Err(e) => {
                eprintln!("警告: {}", e);
                continue;  // 单个文件失败不影响整体搜索
            }
        };

        let results = searcher::search_file(&entry, &config)?;

        if !results.is_empty() {
            file_count += 1;
            match_count += results.len();
            output::print_results(&entry.path, &results, &config);
        }
    }

    println!("\n找到 {} 处匹配，共 {} 个文件", match_count, file_count);
    Ok(())
}

// src/walker.rs — 目录遍历模块
use std::path::{Path, PathBuf};

/// 文件遍历器：递归遍历目录，支持 .gitignore
pub struct FileWalker {
    root: PathBuf,
    max_depth: usize,
    respect_gitignore: bool,
}

/// 遍历到的文件条目
pub struct FileEntry {
    pub path: PathBuf,
}

impl FileWalker {
    pub fn new(root: &str, max_depth: usize,
               respect_gitignore: bool) -> Self {
        FileWalker {
            root: PathBuf::from(root),
            max_depth,
            respect_gitignore,
        }
    }

    /// 返回迭代器，遍历目录中的所有文件
    pub fn iter(&self) -> impl Iterator<Item = Result<FileEntry, walkdir::Error>> + '_ {
        let mut builder = ignore::WalkBuilder::new(&self.root);
        builder.max_depth(Some(self.max_depth));
        builder.git_ignore(self.respect_gitignore);
        builder.hidden(true);  // 跳过隐藏文件

        builder.build().filter_map(|entry| {
            let entry = match entry {
                Ok(e) => e,
                Err(e) => return Some(Err(e)),
            };

            // 只返回文件，跳过目录
            if entry.file_type().map_or(false, |ft| ft.is_file()) {
                Some(Ok(FileEntry {
                    path: entry.path().to_path_buf(),
                }))
            } else {
                None
            }
        })
    }
}

// 实现 IntoIterator 让 FileWalker 可以直接 for 循环
impl IntoIterator for FileWalker {
    type Item = Result<FileEntry, walkdir::Error>;
    type IntoIter = std::vec::IntoIter<Self::Item>;

    fn into_iter(self) -> Self::IntoIter {
        self.iter().collect::<Vec<_>>().into_iter()
    }
}

// src/searcher.rs — 内容搜索模块
use std::fs;
use std::path::Path;
use regex::Regex;
use crate::walker::FileEntry;

/// 搜索配置
pub struct SearchConfig {
    pub pattern: Regex,
    pub ext_filter: Option<String>,
    pub files_only: bool,
}

/// 单个匹配结果
pub struct MatchResult {
    pub line_number: usize,
    pub line_content: String,
    pub match_start: usize,  // 匹配在行中的起始位置
    pub match_end: usize,    // 匹配在行中的结束位置
}

/// 在单个文件中搜索匹配内容
pub fn search_file(entry: &FileEntry, config: &SearchConfig)
    -> anyhow::Result<Vec<MatchResult>> {

    // 按扩展名过滤
    if let Some(ref ext) = config.ext_filter {
        let file_ext = entry.path.extension()
            .and_then(|e| e.to_str())
            .unwrap_or("");
        if file_ext != ext.as_str() {
            return Ok(vec![]);
        }
    }

    // 读取文件内容（跳过二进制文件）
    let content = match fs::read_to_string(&entry.path) {
        Ok(c) => c,
        Err(_) => return Ok(vec![]),  // 二进制文件或无权限，跳过
    };

    let mut results = Vec::new();

    for (line_num, line) in content.lines().enumerate() {
        // 用正则搜索匹配
        if let Some(mat) = config.pattern.find(line) {
            results.push(MatchResult {
                line_number: line_num + 1,
                line_content: line.to_string(),
                match_start: mat.start(),
                match_end: mat.end(),
            });

            // files_only 模式下只需知道文件有匹配即可
            if config.files_only {
                break;
            }
        }
    }

    Ok(results)
}

// src/output.rs — 结果输出模块
use std::path::Path;
use colored::*;
use crate::searcher::{MatchResult, SearchConfig};

/// 格式化输出搜索结果
pub fn print_results(path: &Path, results: &[MatchResult],
                     config: &SearchConfig) {
    // 文件路径：绿色加粗
    println!("\n{}", path.display().to_string().green().bold());

    if config.files_only {
        return;  // 只显示文件名
    }

    for result in results {
        // 行号：蓝色
        let line_num = format!("{:>4}", result.line_number).blue();

        // 匹配内容：匹配部分红色高亮
        let content = highlight_match(
            &result.line_content,
            result.match_start,
            result.match_end,
        );

        println!("{}:{}", line_num, content);
    }
}

/// 高亮匹配部分
fn highlight_match(line: &str, start: usize, end: usize) -> String {
    let before = &line[..start.min(line.len())];
    let matched = &line[start.min(line.len())..end.min(line.len())];
    let after = &line[end.min(line.len())..];

    format!("{}{}{}", before, matched.red().bold(), after)
}

四、项目实战的踩坑记录

踩坑一：正则表达式编译失败：Regex::new() 返回 Result，如果用户输入了无效正则（如 [），程序会崩溃。必须用 ? 传播错误，并给出友好的错误提示。用 anyhow::Context 添加上下文：Regex::new(&pattern).context("正则表达式语法错误")?。

踩坑二：二进制文件导致乱码：fs::read_to_string() 遇到二进制文件会返回 Err，最初我用了 unwrap() 导致崩溃。改为 match 处理：二进制文件直接跳过，不报错也不输出。更完善的方案是检测文件头（如 ELF、PNG 的 magic bytes），主动跳过。

踩坑三：遍历时的权限错误：某些目录没有读权限，walkdir 会返回错误。最初整个遍历会因此中断。改为在遍历中 continue 跳过错误条目，只打印警告，不影响其他文件的搜索。

踩坑四：模块间的循环依赖：最初 searcher.rs 需要引用 walker.rs 的 FileEntry，而 walker.rs 又需要 searcher.rs 的搜索结果——形成了循环依赖。解决方案是将共享的数据结构（FileEntry、MatchResult）定义在独立的模块中，或让数据流单向：walker → searcher → output。

五、总结

非科班转码做 Rust 项目的核心经验：从真实需求出发、小步迭代、踩坑即记录。落地建议：

1. 选真实项目：不要做"计算器"或"待办列表"，做一个自己会用的工具（文件搜索、日志分析、Markdown 转换），有真实需求才有动力。
2. 先跑通再优化：第一版用最简单的方式实现（unwrap、单文件），跑通后再逐步替换为生产级写法（?、模块拆分）。
3. 记录踩坑：每个编译错误都记录原因和解决方案，三个月后你会感谢这些记录。
4. 读别人的代码：在 GitHub 上找同类项目，对比自己的实现，学习更好的写法。推荐阅读 ripgrep（Rust CLI 工具的标杆）的源码。

Rust 的学习曲线确实陡，但每解决一个编译错误，你对内存安全和类型系统的理解就深一层。坚持写真实项目，比刷一百道算法题更有用。