前十篇各讲一块:所有权、类型、trait、错误处理、集合、模块、并发、unsafe。单独看每篇都能跟上,但真正坐到键盘前写一个「有人会用」的程序时,问题会以组合形式出现:参数传进去之后原变量还能不能用、读文件失败怎么把路径带进错误信息、统计结果为什么顺序不稳定、测试该测哪一层。
这一篇不引入新概念,只做一件事:从零写一个命令行工具 logscan,读一份日志文件,统计每个级别出现多少次,支持 --top N 取前几名、--level WARN 只看某个级别。代码只用标准库,不引入任何依赖,整个项目四个源文件,能 cargo run、能 cargo test。
示例在 Rust 2021 edition、当前 stable 下实际编译运行过,输出都是真跑出来的。
先把需求写成可执行的样子
工具的行为定死,后面所有代码都围绕它写:
| 输入 | 行为 |
|---|---|
logscan test.log | 统计所有级别,按次数降序全部输出 |
logscan test.log --top 3 | 只输出前 3 名 |
logscan test.log --level WARN | 只统计 WARN,输出它的次数 |
| 文件不存在 | 打印带路径的错误,退出码 1 |
| 参数非法 | 打印用法提示,退出码 1 |
「级别」的定义先简化:每行按空白切开,第一个词就是级别,比如 WARN disk 91% 里的 WARN。空行跳过。真实日志格式五花八门,这条规则不具备普适性,但它足够让程序跑起来,也留出了后面扩展的位置。
输出长这样:
总计 8 行
WARN 3
ERROR 2
INFO 2
第一行是有效行数,后面每行「级别 + 次数」,级别左对齐占 6 格,为了让列看起来整齐。这个格式不是重点,重点是它把「统计结果」和「展示格式」分开了——统计返回数据,渲染负责排版。
项目结构与模块划分
用 cargo new logscan --edition 2021 建项目,然后把 src/main.rs 拆成四个文件:
src/main.rs 入口:串流程、处理顶层错误、设置退出码
src/cli.rs 参数解析,产出 Options
src/stats.rs 统计逻辑与 Summary,附带单元测试
src/report.rs 把 Summary 渲染成字符串
划分依据是「谁依赖谁」:cli 不依赖任何业务类型,stats 只依赖标准库,report 依赖 stats::Summary,main 依赖三者。依赖是单向的,所以每一块都能单独测试、单独替换。第 8 篇讲过 mod 与 pub,这里直接拿来用:三个模块都只公开一个类型或一个函数,别的都留在模块内部。
入口文件负责三件事:声明模块、把参数和文件内容交给统计、把渲染结果打印出去。它也负责最后一件事——把错误变成人类看得懂的一行字和正确的退出码。
mod cli;
mod report;
mod stats;
use std::error::Error;
use std::fs;
fn main() {
if let Err(e) = run() {
eprintln!("错误: {e}");
std::process::exit(1);
}
}
fn run() -> Result<(), Box<dyn Error>> {
let opts = cli::Options::parse(std::env::args().skip(1))?;
let text = fs::read_to_string(&opts.path).map_err(|e| {
std::io::Error::new(e.kind(), format!("读取 {} 失败: {e}", opts.path))
})?;
let summary = stats::summarize(&text, opts.level.as_deref());
print!("{}", report::render(&summary, opts.top));
Ok(())
}
这里有个小设计:main 本身不返回 Result,而是调用 run 并处理它的错误。为什么?因为 main 返回 Err 时,标准运行时会用 Debug 格式打印错误,像 Error: Os { code: 2, kind: NotFound, ... } 这种,对用户不友好。自己接住错误、用 eprintln 打印、再 exit(1),输出干净,退出码也明确。第 6 篇讲过 ? 和 main 返回 Result 的边界,这里就是把那个边界收回来自己管。
为什么错误类型是 Box<dyn Error>?因为这个小工具有两类错误:I/O 错误(文件读不到)和参数错误(用户输错)。用一个盒子装不同类型的错误,? 就能自动转换,不用为每种错误写一个枚举。代价是丢失具体类型,调用方没法用 downcast 之外的方式区分——对命令行工具够用,对库就不合适。第 6 篇的边界讨论在这里落地。
参数解析:不引入依赖也能做
真实项目通常用 clap,这里故意手写,是为了看清「解析参数」到底在做什么,以及所有权在这里怎么流动。
use std::error::Error;
use std::io;
pub struct Options {
pub path: String,
pub top: usize,
pub level: Option<String>,
}
fn usage(msg: &str) -> io::Error {
io::Error::new(io::ErrorKind::InvalidInput, msg.to_string())
}
impl Options {
pub fn parse(mut args: impl Iterator<Item = String>) -> Result<Self, Box<dyn Error>> {
let path = args
.next()
.ok_or_else(|| usage("用法: logscan <日志文件> [--top N] [--level LEVEL]"))?;
let mut top = usize::MAX;
let mut level = None;
while let Some(arg) = args.next() {
match arg.as_str() {
"--top" => {
let value = args.next().ok_or_else(|| usage("--top 需要一个数字"))?;
top = value.parse().map_err(|_| usage("--top 必须是正整数"))?;
}
"--level" => {
level = Some(args.next().ok_or_else(|| usage("--level 需要一个值"))?);
}
other => return Err(usage(&format!("未知参数: {other}")).into()),
}
}
Ok(Options { path, top, level })
}
}
几个细节。第一,参数迭代器按值接收 String,因为解析完要把 path 和 level 存进 Options,而不是借来一个临时值。第二,top 默认是 usize::MAX,配合渲染层的 take(top) 就等于「不限制」,不用额外写 Option<usize> 分支。第三,level 用 Option<String> 表示「可能没指定」;后面传给统计函数时用 as_deref() 转成 Option<&str>,避免把所有权交出去。
为什么错误用 io::Error 而不是自定义类型?因为 io::Error 实现了 Error,能直接进 Box<dyn Error>,而 &str 不行。写 ok_or("...")? 会编译失败,提示 the trait bound `&str: Error` is not satisfied。这是第 6 篇那个「? 会做 From 转换」的直接应用:目标类型是 Box<dyn Error>,只要源错误实现了 Error + 'static,就能自动装箱。
手写解析的边界也很清楚:不支持 --top=3 这种等号形式,不支持短选项 -t,不支持 --help,参数顺序也要求「文件在前」。这些都能加,但每加一条,解析代码就长一截。到了这个阶段,引入 clap 往往比继续手写划算——这是「不引入依赖」的代价,后面还会展开。
统计核心:HashMap、过滤与稳定排序
统计模块是整个工具里唯一有业务逻辑的地方,也最适合写单元测试。它接收整段文本和一个可选的级别过滤条件,返回一个可渲染的 Summary。
use std::collections::HashMap;
pub struct Summary {
pub total: usize,
pub counts: Vec<(String, u32)>,
}
pub fn summarize(text: &str, level: Option<&str>) -> Summary {
let mut counts: HashMap<&str, u32> = HashMap::new();
let mut total = 0usize;
for line in text.lines() {
let line = line.trim();
if line.is_empty() {
continue;
}
total += 1;
let name = line.split_whitespace().next().unwrap_or("UNKNOWN");
if level.is_some_and(|wanted| name != wanted) {
continue;
}
*counts.entry(name).or_insert(0) += 1;
}
let mut counts: Vec<(String, u32)> = counts
.into_iter()
.map(|(k, v)| (k.to_string(), v))
.collect();
counts.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(&b.0)));
Summary { total, counts }
}
这段几乎把第 7 篇复习了一遍:lines() 逐行遍历、trim 去空白、split_whitespace 取第一个词、entry().or_insert(0) 计数。total 统计的是「有效行数」,空行不算;过滤只影响 counts,不影响 total。这个语义要提前定清楚,不然用户会疑惑「为什么 --level WARN 时总数还是 8」。
summary.counts 从 HashMap 转成 Vec 是必须的:HashMap 的遍历顺序不确定,直接输出会每次都不一样。排序用了两个键:先按次数降序,次数相同再按级别名字升序。第二个键不是为了好看,是为了让结果可预测——否则 INFO 和 WARN 都是 2 次时,谁在前取决于哈希,测试会随机失败。
这里有个真实的小插曲。第一次写测试时,我以为 WARN 会排在 INFO 前面,断言写成了 counts[0] == ("WARN", 2),跑 cargo test 直接失败:
assertion `left == right` failed
left: ("INFO", 2)
right: ("WARN", 2)
原因就是上面说的次要排序键:两者次数相同,按字母序 INFO 在前。这不是程序错了,是我对「同次数时怎么排」没有想清楚。把断言改成 INFO 在前,测试通过。这个经历正好说明单元测试的价值:它逼你把「相等时怎么办」这种边界写下来,而不是靠运行一次碰运气。
过滤那行用了 is_some_and,它是 Option 上的方法,意思是「有值并且满足条件」。等价写法是 if let Some(wanted) = level { if name != wanted { continue; } }。前者更短,但第一次见可能要想一下;两种都能读,选团队熟悉的。第 4 篇讲过 Option 的组合方法,这里是一个实际用例。
渲染:把数据和排版分开
渲染层只有一个函数,作用是把 Summary 变成最终要打印的字符串:
use crate::stats::Summary;
pub fn render(summary: &Summary, top: usize) -> String {
let mut out = format!("总计 {} 行\n", summary.total);
for (level, n) in summary.counts.iter().take(top) {
out.push_str(&format!("{level:<6} {n}\n"));
}
out
}
为什么返回 String 而不是直接 println!?因为「生成文本」和「输出文本」是两件事。返回字符串的版本可以在测试里断言内容,也可以被别的输出目标复用(写文件、发 HTTP)。直接在函数里打印,测试就只能捕获标准输出,麻烦得多。这个分离很小,但决定了这段逻辑能不能被测试。
{level:<6} 是格式化语法:左对齐、宽度 6。级别名超过 6 个字符时不会截断,只是不再补空格,列会错位——这是格式化的固有限制,不是 bug。要严格对齐得先算最大宽度,再动态补空格;对这个小工具不值得。知道边界在哪,比强行完美更重要。
take(top) 是迭代器适配器,不产生新的 Vec,只是限制取多少个。这里 top 可能是 usize::MAX,take 会一直取到结束,行为正确。第 7 篇讲过迭代器是惰性的,这里正好体现了它的好处:不需要为「取前 N 个」写两套分支。
测试:只测纯函数
测试写在 stats.rs 底部,用 #[cfg(test)] 让它们只在测试构建里编译:
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn counts_by_level() {
let text = "INFO a\nWARN b\nWARN c\n\nINFO d\n";
let s = summarize(text, None);
assert_eq!(s.total, 4);
assert_eq!(s.counts[0], ("INFO".to_string(), 2));
assert_eq!(s.counts[1], ("WARN".to_string(), 2));
}
#[test]
fn filters_by_level() {
let text = "INFO a\nWARN b\nWARN c\n";
let s = summarize(text, Some("WARN"));
assert_eq!(s.total, 3);
assert_eq!(s.counts.len(), 1);
assert_eq!(s.counts[0], ("WARN".to_string(), 2));
}
}
cargo test 实测结果:
running 2 tests
..
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
为什么只测 summarize?因为它是纯函数:给定输入文本,输出确定的 Summary,不碰文件、不碰标准输出、不依赖环境。纯函数最好测,一个字符串就能构造场景。参数解析和文件读取也可以测,但需要构造参数迭代器和临时文件,成本高一些,收益在项目变大后才明显。这个取舍不是偷懒,是把测试预算花在最容易出错、又最容易测的地方。
测试里有个细节:assert_eq!(s.counts[0], ("INFO".to_string(), 2)) 右边是元组 (String, u32),和左边类型一致。如果写成 ("INFO", 2),类型是 (&str, i32),编译不过——assert_eq! 要求两边类型能比较,这里没有隐式转换。第一次写测试时这种类型不匹配很常见,改法就是显式 to_string() 和字面量后缀,或者用 &s.counts[0] 和 &("INFO".to_string(), 2) 比较引用。
跑起来:正常、过滤、出错
准备一份 test.log,八行有效内容,四种级别:
WARN disk 91%
INFO started
WARN disk 92%
ERROR db timeout
INFO request ok
WARN cpu 95%
ERROR db timeout
DEBUG cache hit
看前三名:
cargo run -- test.log --top 3
总计 8 行
WARN 3
ERROR 2
INFO 2
只看 WARN:
cargo run -- test.log --level WARN --top 2
总计 8 行
WARN 3
注意 --top 2 在这里只限制了显示条数,过滤后本来就只剩一条。文件不存在时:
cargo run -- nope.log
错误: 读取 nope.log 失败: 系统找不到指定的文件。 (os error 2)
这行错误里同时有「我们加的上下文」和「系统给的原始信息」,比只打印 No such file or directory 有用得多——用户知道是哪个文件。参数写错时:
cargo run -- test.log --top abc
错误: --top 必须是正整数
退出码也按约定返回 1。在 shell 里可以用 echo $?(Windows PowerShell 用 $LASTEXITCODE)确认。脚本调用命令行工具时,退出码比输出文本更重要:0 表示成功,非 0 表示失败,这是自动化流程判断的依据。
cargo run -- 后面的 -- 是 Cargo 的分隔符:它左边是给 cargo 的参数,右边才是给程序的参数。漏掉它会得到「unexpected argument」之类的 Cargo 错误,而不是程序自己的错误。现象对照:把这个工具改坏会发生什么
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
borrow of moved value: `args` | 参数迭代器或 String 被 move 进某个函数后又想用 | 改成传 &str/&String,或让原变量不再被使用 |
cannot borrow `counts` as mutable because it is also borrowed as immutable(E0502) | 一边遍历 counts 一边 insert/remove | 遍历期间只读;要改结构就先收集修改,循环后执行 |
missing lifetime specifier(E0106),函数返回 &str 且有两个引用参数 | 返回值借自哪个参数没说清楚 | 给相关参数和返回值标同一个生命周期,或直接返回 String |
`Rc<...>` cannot be sent between threads safely(E0277) | 想把统计结果用 Rc/RefCell 共享给多线程 | 换 Arc;要共享修改再加 Mutex |
the `?` operator can only be used in a function that returns `Result` or `Option`(E0277) | 在返回 () 的 main 或闭包里用了 ? | 把逻辑挪进返回 Result 的 run,或处理错误而不是传播 |
type annotations needed 指向 .collect() | 不知道要收集成 Vec 还是别的容器 | 给变量标 Vec<_>,或用 collect::<Vec<_>>() |
| 测试偶发失败,两个级别次数相同但顺序不同 | 排序只按次数,没定义同次数时的次序;HashMap 顺序不确定 | 加次要排序键(如级别名字),让结果可预测 |
错误: 读取 xxx 失败: ... 里的路径不对 | opts.path 被后续代码移动或覆盖 | 检查 Options 的生命周期,确认打印前没有 move |
| 输出里级别列没对齐 | 级别名超过格式宽度,或终端不是等宽字体 | 先算最大宽度动态补空格;确认展示环境 |
边界与代价
第一层是「整文件读入」的内存代价。fs::read_to_string 把整个文件加载进内存,100 MB 的日志就要 100 MB 内存,1 GB 的日志可能直接把进程拖垮。真实日志工具应该用 BufReader 配合 lines() 流式处理,内存占用只跟缓冲区大小有关。代价是代码复杂度上升:要处理逐行 I/O 错误、不能随手 read_to_string、借用生命周期也更麻烦。小文件用整读,大文件用流式,这是按场景选,不是谁更高级。
第二层是 UTF-8 假设。read_to_string 遇到非 UTF-8 字节会返回错误,而现实中的日志可能是 GBK 编码、可能混入二进制内容。要处理就得按字节读(read)再自行解码,或用 encoding_rs 这类库。当前版本明确只支持 UTF-8,这是一个需要写进文档的限制,而不是让用户在报错里猜。
第三层是解析规则的脆弱性。「第一个空白分隔的词是级别」只适用于格式规整的日志。真实日志有 JSON 行、有带时间戳前缀的、有多行堆栈。真要做通用工具,要么让用户指定格式(正则或模板),要么只支持一种明确格式并说清楚。当前版本选后者:规则简单、可预测,遇到不认识的格式会把它归到第一个词,至少不会崩。
第四层是不引入依赖的代价。手写参数解析不支持 --help、等号形式、短选项、参数校验的组合,做到后面会越来越像在重写 clap。标准库能覆盖「三五个参数」的场景,再复杂就该引入成熟库。同理,错误类型用 Box<dyn Error> 省了定义枚举,但调用方无法区分错误种类;库代码通常用 thiserror 定义具体错误,应用代码用 anyhow 加上下文。这些选择没有对错,只有「这个项目的规模撑不撑得起」。
第五层是性能。当前实现单线程、整读、HashMap 计数,处理几 MB 的日志在毫秒级,完全够用。真到几百 MB、多个文件,才需要并行:第 9 篇的 thread::scope 可以把多个文件分给多个线程,每个线程产出局部 Summary,主线程合并。合并时要重新累加计数并再排一次序。注意别为了「看起来高级」提前上线程——单线程跑 10 毫秒的程序,加线程只会更慢。
最后是测试边界。单元测试覆盖了纯函数,但没覆盖「文件读不到」「参数非法」「退出码」这些集成行为。要测它们,需要 tests/ 目录下的集成测试,用 std::process::Command 跑编译出的二进制,构造临时文件,断言 stdout 和退出码。这类测试更慢、更脆,但能抓住「用户实际看到什么」的问题。测试金字塔不是教条:核心逻辑多写单元测试,关键路径补少量集成测试。
小结:这一组的基础到此为止
这个工具虽小,前十篇的东西基本都用上了:所有权决定 Options 里存 String 还是 &str、? 与 Box<dyn Error> 决定错误怎么传、HashMap 加 entry 做计数、排序定义同次数时的次序、模块把解析/统计/渲染分开、单元测试守住纯函数、退出码让脚本能判断成败。并发和 unsafe 没有硬塞进来,因为这个小工具暂时不需要——知道什么时候不用,和知道怎么用同样重要。
但这个工具只覆盖了「单机、单进程、同步」的写法。文件读写的完整语义、TCP 的消息边界、子进程的收尾、跨进程共享、异步运行时,属于下一组系统接口篇,从第 12 篇的文件系统开始。那里会继续用这里的所有权与错误处理,只是把场景换成了真实操作系统。
如果要继续往前走,三个方向最自然:把整读改成流式,处理更大的文件;把多文件输入接上 thread::scope 并行统计;把错误类型从 Box<dyn Error> 换成具体枚举,让调用方可以区分「文件不存在」和「格式错误」。每一个都不需要新语言特性,只是把已有工具组合得更深。
当天可以自己验证的练习:
- 把这篇的四个文件敲进一个
cargo new项目,跑通cargo run -- test.log --top 3,确认输出和文中一致。 - 给
Options加一个--min N,只显示次数不少于 N 的级别;想清楚过滤放在统计层还是渲染层。 - 把
read_to_string改成BufReader::new(File::open(...)?).lines()的流式版本,用一个 10 万行的生成文件对比内存占用和耗时。 - 写一个集成测试:用
std::process::Command运行二进制,传入不存在的文件,断言退出码是 1 且 stderr 含「读取」。 - 把
summarize改成同时接收多个文件路径,用thread::scope并行读取和统计,最后合并结果;确认合并后的排序仍然稳定。
这组文章从「为什么要有所有权」讲到「写一个能跑的小工具」,路径是完整的。如果中间有哪一篇读得吃力,回到那一篇把示例亲手敲一遍,比继续往下翻更有效。Rust 的学习曲线陡在开头,过了所有权和错误处理这两关,后面的东西大多是这两条的延长线。接下来可以往标准库深处走(异步、宏、trait 对象),也可以直接挑一个开源项目读源码——两种都比再刷一遍教程有用。