上一篇的日志统计程序,所有代码都塞在一个 main.rs 里。七十行还能忍,可一旦加上参数解析、文件读取、输出格式、单元测试,很快就是三百行起步。再往后,同事想只复用「统计」这一块,发现它和打印、命令行参数缠在一起,只能整段复制。这就是写 Rust 项目最早遇到的结构问题:不是语法不会,而是不知道怎么拆。
Rust 给的答案分三层。模块负责在一个 crate 内部切分代码和可见性,crate 是编译和复用的最小单位,workspace 把多个相关的 crate 放在一个仓库里一起管理。三层各自解决不同的问题,混在一起讲最容易乱。这篇按顺序走:先拆模块,再讲 crate 的库与二进制,最后用 workspace 把统计核心和命令行前端分开。
所有示例都在 Rust 2021 edition 下,用 cargo 直接跑,输出是实际运行过的。
场景走查:把一个 main.rs 拆成三个模块
先用需求把结构逼出来。这个日志工具要做三件事:解析命令行参数(--top N)、统计日志里各级别出现的次数、把结果格式化成文本输出。三件事彼此独立,正好对应三个模块。拆分后的文件布局是:
src/main.rs 入口,声明模块并串流程
src/cli.rs 参数解析
src/stats.rs 统计逻辑与数据结构
src/report.rs 文本渲染
注意这里没有目录,四个文件平铺在 src/ 下。模块不一定对应文件夹,单文件模块是最常见的形式。下面逐个写。
入口文件用 mod 声明子模块,再把要用到的名字 use 进来:
mod cli;
mod report;
mod stats;
use cli::Options;
fn main() {
let opts = Options::parse(std::env::args().skip(1));
let lines = [
"WARN disk 91%",
"INFO started",
"WARN disk 92%",
"ERROR db timeout",
"WARN cpu 95%",
];
let summary = stats::summarize(&lines);
print!("{}", report::render(&summary, opts.top));
}
mod cli; 这句话的意思是「把 src/cli.rs 作为本模块的子模块挂进来」。分号结尾表示内容在别的文件里;如果写成花括号 mod cli { ... },内容就写在同一文件内。编译器按这个声明去找文件,所以漏写 mod 就拿不到那个文件——文件存在不等于模块存在,这是新手最容易误会的一点。
参数解析模块:
pub struct Options {
pub top: usize,
}
impl Options {
pub fn parse(args: impl Iterator<Item = String>) -> Self {
let mut top = usize::MAX;
let mut it = args;
while let Some(a) = it.next() {
if a == "--top" {
if let Some(v) = it.next() {
if let Ok(n) = v.parse() {
top = n;
}
}
}
}
Options { top }
}
}
统计模块沿用上一篇的 HashMap 计数和排序,只是把结果包成一个结构体,并把字段公开:
use std::collections::HashMap;
pub struct Summary {
pub counts: Vec<(String, u32)>,
}
pub fn summarize(lines: &[&str]) -> Summary {
let mut counts: HashMap<&str, u32> = HashMap::new();
for line in lines {
let level = line.split_once(' ').map(|(l, _)| l).unwrap_or(line);
*counts.entry(level).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 { counts }
}
渲染模块只依赖 Summary,用 crate::stats::Summary 这个完整路径引用同 crate 里的兄弟模块:
use crate::stats::Summary;
pub fn render(summary: &Summary, top: usize) -> String {
let mut out = String::new();
for (level, n) in summary.counts.iter().take(top) {
out.push_str(&format!("{level}: {n}\n"));
}
out
}
跑起来:
cargo run -- --top 2
WARN: 3
ERROR: 1
实际输出就是这样。数据里 WARN 出现 3 次、ERROR 1 次、INFO 1 次,按次数降序取前 2 名,同次数再按字母序。--top 2 被 cli 解析成 2,report 用 take(2) 截断。三个模块各管一段,main 只负责串起来。
这张依赖图里没有箭头,但方向很清楚:report 依赖 stats 的类型,main 依赖三者。cli 谁都不依赖,所以它可以被单独测试、单独复用。拆模块的第一原则就是尽量让依赖朝一个方向流,别让 stats 反过来调用 report 里的打印函数。
mod 与路径:名字从哪来,怎么找
Rust 的模块路径有三条相对起点,记熟它们比记语法有用:
| 写法 | 含义 | 典型场景 |
|---|---|---|
crate:: | 从当前 crate 根开始 | 跨模块引用,最稳 |
super:: | 父模块 | 子模块引用父模块的东西 |
self:: | 当前模块 | 写全路径时消除歧义 |
| 直接写名字 | 先在当前模块找,再在 use 引入的名字里找 | 同模块内调用 |
use 只是把名字带进当前作用域,不改变它定义在哪。所以 report.rs 里写 use crate::stats::Summary,等价于后面每次用到都写全 crate::stats::Summary。用 use 的另一个好处是导入整组:use std::collections::{HashMap, BTreeMap};,花括号里可以列多个名字。
模块文件还能再嵌套。如果 stats 变大,拆成目录:
src/stats.rs 或 src/stats/mod.rs 模块入口
src/stats/parse.rs 子模块 stats::parse
src/stats/rank.rs 子模块 stats::rank
此时 stats.rs 里要写 pub mod parse;、pub mod rank;,子模块才存在。2018 edition 之后推荐 src/stats.rs 这种「同名文件 + 同名目录」的写法,mod.rs 是旧风格,仍能用但不推荐新项目采用——它让目录里出现一堆同名 mod.rs,编辑器和搜索都更容易看错。
还有一个常被问的问题:模块之间能不能互相引用?同一个 crate 内可以,a 引 b、b 引 a 编译器不会拦,只要别在类型定义层面形成无限递归(比如结构体直接包含自己,那需要 Box 间接)。但 crate 之间不行,Cargo 会直接拒绝循环依赖。这条限制是 workspace 划分的重要依据,后面会再提。
pub:默认私有,以及四档可见性
Rust 的默认规则和很多语言相反:所有东西默认私有,包括模块、函数、结构体、字段、枚举变体(枚举变体例外,跟着枚举走)。想给外面看,必须显式写 pub。
为什么默认私有?因为「公开」是一个承诺。一旦别的模块依赖了你的函数签名,你改参数、改返回类型就可能破坏对方;而私有项你可以随时重构。默认收紧,等于逼你想清楚「这个 API 我要不要负责到底」。
可见性有四档,按范围从小到大:
| 写法 | 谁能访问 | 使用建议 |
|---|---|---|
| 不写(私有) | 当前模块及其子模块 | 实现细节,默认选它 |
pub(super) | 父模块 | 只给直接上级用 |
pub(crate) | 整个 crate 内部 | 跨模块共享但不对外 |
pub | 任何依赖此 crate 的代码 | 真正的公开 API |
一个高频坑:结构体的字段要单独标 pub。pub struct Summary 只公开了「有这么一个类型」,里面的 counts 字段仍是私有的。于是 report 里访问 summary.counts 会报:
error[E0616]: field `counts` of struct `Summary` is private
--> src/report.rs:5:31
|
5 | for (level, n) in summary.counts.iter().take(top) {
| ^^^^^^ private field
人话版:类型是公开的,但字段没公开。这种设计其实很有用——你可以公开一个结构体,同时把字段藏起来,只允许通过构造函数和方法访问,以后改内部表示就不破坏调用方。pub struct Summary { counts: Vec<(String, u32)> } 配合一个 pub fn counts(&self) -> &[(String, u32)] 就是「字段私有、接口公开」的常见写法。这里为了简单,直接给字段加了 pub。
另一个工具是 pub use,即「重导出」:把别处的名字在本模块公开出去。lib.rs 里写 pub use config::Config;,外部用户就可以 use 你的crate::Config,不必知道 Config 实际藏在 config 模块里。这是做「门面」的标准手法:内部结构随意调整,对外只暴露一层薄接口。
Config 本身是 pub,它所在的 config 模块是私有的,外部照样进不来。报错会同时指出「模块私有」和「类型没有公开重导出」。crate:lib.rs 与 main.rs 是什么关系
一个 Cargo 包(package)可以产出一个或多个 crate。最常见的是两种:
src/lib.rs,给别的代码 use,没有 mainsrc/main.rs(或 src/bin/*.rs),产出可执行文件为什么要把逻辑放库里?因为库能被测试、能被别的 crate 依赖,而二进制只能运行。把统计逻辑留在 main.rs 里,单元测试虽然也能写(#[cfg(test)] mod tests),但外部项目没法复用。拆成库之后,命令行只是它的一個使用者。
这里最容易踩的坑是路径。假设包名 logcore,lib.rs 里写的是私有模块:
// src/lib.rs
mod config;
pub use config::Config;
然后 src/main.rs 里试图直接走模块路径:
use logcore::config::Config;
error[E0603]: module `config` is private
--> src/main.rs:1:17
|
1 | use logcore::config::Config;
| ^^^^^^ ------ struct `Config` is not publicly re-exported
| |
| private module
|
note: the module `config` is defined here
--> src/lib.rs:1:1
|
1 | mod config;
| ^^^^^^^^^^
人话版:main.rs 是另一个 crate(二进制 crate),它看 lib.rs 就像看外部依赖。库只公开了 Config 这个名字(通过 pub use),没公开通往它的 config 模块,所以不能从模块路径走。正确写法是 use logcore::Config;;如果确实想保留模块路径,就把 mod config; 改成 pub mod config;。
两种修法对应两种设计取向。pub use 是「只给成品,不给零件」,适合对外 API;pub mod 是「整条路径都开放」,适合内部多 crate 协作、想让别人按模块挑着用。多数库选择前者,把内部模块藏起来,日后好重构。
另外,src/main.rs 和 src/lib.rs 同时存在时,Cargo 会编出两个 crate:库名默认是包名(连字符换成下划线),二进制名也是包名。二进制里用 use 包名::... 引用自己的库,而不是 crate::——crate:: 在二进制里指的是二进制自己的根,两者不是同一个东西。这个区别第一次遇到时非常反直觉。
workspace:把核心库和命令行分开
当项目从「一个工具」长成「一个核心库 + 一个命令行 + 以后可能还有服务端」,就该用 workspace。它把多个 crate 放进一个仓库,共享一份锁文件和一个 target 目录,一条命令可以构建全部。
目录结构:
Cargo.toml 工作区根,只写 members
core/Cargo.toml 包 logcore,库
core/src/lib.rs
cli/Cargo.toml 包 logcli,二进制
cli/src/main.rs
根 Cargo.toml:
[workspace]
resolver = "2"
members = ["core", "cli"]
resolver = "2" 是 Rust 2021 推荐的特性解析器,能避免一些依赖特性被意外合并的问题。新项目写上它。
cli/Cargo.toml 用路径依赖指向同仓库的库:
[package]
name = "logcli"
version = "0.1.0"
edition = "2021"
[dependencies]
logcore = { path = "../core" }
cli/src/main.rs 就只做参数和输出,统计全交给 logcore:
use logcore::summarize;
fn main() {
let lines = ["WARN disk", "INFO started", "WARN cpu", "ERROR db", "WARN mem"];
let summary = summarize(&lines);
for (level, n) in summary.counts.iter().take(2) {
println!("{level}: {n}");
}
}
在工作区根目录运行指定包:
cargo run -p logcli
WARN: 3
ERROR: 1
实测输出与前面单包版本一致。注意 -p 后面跟的是包名,不是目录名;cargo run 不带 -p 时,如果工作区里有多个二进制包,Cargo 会要求你指定,报错里会列出候选。这是 workspace 带来的第一处日常摩擦,习惯就好。
workspace 还有两个实用配置。根 Cargo.toml 可以写 [workspace.dependencies] 集中声明版本,成员里用 serde = { workspace = true } 继承,避免两个包各自写不同版本导致同一依赖被编两遍。还可以加 [workspace.lints] 统一 lint 规则。这些都属于项目规模化之后的整理,不是第一天就要配。
什么时候该用 workspace?三个信号:有多个可执行文件共享同一套逻辑;库要单独发布到 crates.io,而工具不发布;构建时间变长、想只编改动的包。反过来说,一个只有几十行的工具硬拆 workspace,只会让 cargo run 多一层选择,得不偿失。
常见报错怎么读
模块相关的报错其实就几类,认准关键词就能定位。
unresolved import(E0432)——名字根本找不到。常见于拼错、忘了 pub、或者路径起点写错。编译器常常顺带给一个相似名字的建议:
error[E0432]: unresolved import `cli::Option`
--> src/main.rs:5:5
|
5 | use cli::Option;
| ^^^^^------ no `Option` in `cli`
|
help: a similar name exists in the module
|
5 | use cli::Options;
| +
这里 Options 少写了一个 s,编译器在 cli 里找到了拼写相近的名字。照着 help 补一个字符即可。如果没有这条建议,先确认模块里确实有这个名字,再看它是不是 pub。
cannot find type(E0433)——名字没进作用域。它通常跟在 E0432 后面出现:导入失败了,后面用这个名字自然找不到。修好第一个报错,后面一串常常一起消失。不要从最后一条报错往前改。
is private(E0603 / E0616)——名字找得到,但你没权限。E0603 针对模块和函数(function `summarize` is private),E0616 针对字段。人话版是「我看得见它,但它锁着门」。先确认这个项是不是故意不公开;如果确实要公开,就给模块/函数/字段补 pub,或者用 pub use 重导出。
读报错还有两个通用技巧。第一,看 note: ... is defined here,它会跳转到定义位置,能立刻判断是「定义时没公开」还是「引用时路径错了」。第二,看 help 里的建议代码,Rust 的 help 经常直接给出可用的修复行,照着改通常就过。真正需要理解的是前半句的性质:找不到、没权限、还是类型不对。
现象对照
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
file not found for module / 明明有文件却提示模块不存在 | 没有在父模块写 mod xxx;,文件不会自动变成模块 | 检查父模块(或 lib.rs/main.rs)里有没有对应的 mod 声明 |
unresolved import,还提示相似名字 | 名字拼错或路径起点错,crate:: 与 super:: 混用 | 按 help 的相似建议改;再确认模块层级和路径起点 |
function ... is private(E0603) | 函数没写 pub,默认私有 | 看 note: defined here,给函数补 pub 或用 pub use 暴露 |
module ... is private(E0603,跨 crate) | 库里的模块是 mod 而不是 pub mod,外部不能走模块路径 | 改用 use 包名::类型名(依赖重导出),或把模块改成 pub mod |
field ... is private(E0616) | pub struct 只公开类型,字段仍默认私有 | 给字段加 pub,或提供 getter / 构造函数 |
二进制里 use crate::xxx 找不到库里的类型 | crate:: 指二进制自己的根,不是同包库的根 | 改成 use 包名::xxx |
workspace 里 cargo run 要你指定包 | 工作区有多个二进制,Cargo 无法替你选 | 加 -p 包名,或用 default-members 指定默认 |
两个 crate 互相 use 对方 | Cargo 不允许 crate 循环依赖 | 把共用部分下沉到第三个库 crate,形成单向依赖 |
边界与代价
第一层代价是「拆得太碎」。每多一个模块,就多一次跨文件跳转;每多一个 pub,就多一份兼容性责任。三个函数的模块还不如就放在一起。判断标准不是行数,而是「这组东西是不是围绕同一个概念、会不会被独立复用或独立测试」。围绕一个概念的代码放一起,哪怕三百行也不该硬拆;两个概念混在一起,哪怕各十行也该分。
第二层代价是可见性收紧带来的连锁反应。把字段设为私有、只留 getter,调用方就多一层方法调用,有时还要多写 as_ref、to_vec 这类转换。这是用一点书写成本换重构自由,值得,但别在内部小工具里过度封装——同一个 crate 内,pub(crate) 通常比私有加 getter 更省事,因为 crate 边界才是真正的契约边界。
第三层是 workspace 的构建与版本耦合。所有成员共享 Cargo.lock,一个包升级依赖,全部包一起受影响;target 目录共享省了编译时间,但特性合并(feature unification)可能让某个包拿到它没主动开启的特性。排查这类问题时,cargo tree -e features 比猜有用。另一个选择是干脆拆成多个独立仓库,用发布版本互相依赖,代价是改一行要发版、等版本对齐。取舍取决于团队规模和发布节奏。
第四层是发布边界。库一旦发布到 crates.io,pub 的 API 就成了契约,删改都算破坏性变更。所以「哪些该 pub」不是写完就定的事,而是要在第一次发布前想清楚。内部 crate 之间互调用 pub(crate) 或独立 workspace 包,可以避开大部分这类压力。
最后提醒一个容易被忽略的实践:模块的公开面越小,编译和心智负担越低。一个模块十几个 pub fn、二十几个 pub struct,外面根本不知道该用哪个。把常用入口 pub use 到 crate 根,其余留在模块内,是让库「看起来小」的有效办法。
小结
mod 声明子模块,文件不会自动变成模块;use 只是引入名字,路径靠 crate::、super::、self:: 定位。Rust 默认私有,pub、pub(crate)、pub(super) 四档按范围选,结构体字段要单独公开。
一个包可以有库 crate 和二进制 crate,逻辑放 lib.rs、壳放 main.rs;二进制看同包的库要写 use 包名::...,不是 crate::...。多个相关 crate 用 workspace 组织,共享锁文件和构建目录,用 -p 指定运行哪个。
当天可以自己验证的练习:
- 把这篇的四个文件亲手敲一遍,运行
cargo run -- --top 3,确认输出三行且顺序正确。 - 删掉
main.rs里的mod report;,观察报错是不是「模块不存在」,再把它加回来。 - 把
Summary的pub counts改成私有,读一遍 E0616,然后加一个pub fn counts(&self) -> &[(String, u32)]并改掉report的访问方式。 - 把
lib.rs的pub mod config;改回mod config;,在main.rs里分别用logcore::Config和logcore::config::Config试一遍,记住哪个能过、为什么。 - 把单包项目改成 workspace 的两包结构,用
cargo run -p logcli跑通,再用cargo build观察两个包共享一个target。
下一篇讲并发:线程、channel 与共享状态。现在模块把代码分清楚了,但程序还是一条线从头跑到尾。真实工具常常要同时读多个文件、把统计分给几个线程,再汇总结果。线程让「谁拥有数据」这个问题重新变得尖锐:move 进闭包意味着什么、为什么 Rc 不能跨线程、Arc<Mutex> 又贵在哪,都是下一篇的内容。