上一篇的日志统计程序,所有代码都塞在一个 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 只负责串起来。

依赖方向:入口只依赖三个叶子模块
main 串流程
cli 解析参数
stats 统计
report 渲染

这张依赖图里没有箭头,但方向很清楚: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。最常见的是两种:

库 crate:入口是 src/lib.rs,给别的代码 use,没有 main
二进制 crate:入口是 src/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 指定运行哪个。

当天可以自己验证的练习:

  1. 把这篇的四个文件亲手敲一遍,运行 cargo run -- --top 3,确认输出三行且顺序正确。
  2. 删掉 main.rs 里的 mod report;,观察报错是不是「模块不存在」,再把它加回来。
  3. 把 Summary 的 pub counts 改成私有,读一遍 E0616,然后加一个 pub fn counts(&self) -> &[(String, u32)] 并改掉 report 的访问方式。
  4. 把 lib.rs 的 pub mod config; 改回 mod config;,在 main.rs 里分别用 logcore::Config 和 logcore::config::Config 试一遍,记住哪个能过、为什么。
  5. 把单包项目改成 workspace 的两包结构,用 cargo run -p logcli 跑通,再用 cargo build 观察两个包共享一个 target。

下一篇讲并发:线程、channel 与共享状态。现在模块把代码分清楚了,但程序还是一条线从头跑到尾。真实工具常常要同时读多个文件、把统计分给几个线程,再汇总结果。线程让「谁拥有数据」这个问题重新变得尖锐:move 进闭包意味着什么、为什么 Rc 不能跨线程、Arc<Mutex> 又贵在哪,都是下一篇的内容。