第7章 工程组织与测试举证
第 7 章 · 工程组织与测试举证
本章要回答的三个问题：代码多了怎么划分管辖权（模块）？依赖与构建怎么管理（Crates 与 Cargo）？怎么证明代码按判决执行（测试）？
为什么要有这一章
玩具程序一个文件即可，真实工程的核心难题是边界：哪些东西对外可见、哪些内部私有；依赖的版本怎么锁定；行为凭什么可信。Rust 用模块系统管理可见性、用 Cargo 管理依赖闭环、用内建测试框架管理举证责任——测试代码与生产代码同处一个文件，无需外部测试框架。
读完能解决什么
- 用 mod、pub、use 组织多模块项目并控制可见性；
- 理解 crate 作为编译单元、workspace 组织多 crate 仓库；
- 写单元测试、集成测试与文档测试并按目标运行。
各节怎么分工
| 节 | 回答哪个问题 | 关键产出 |
|---|---|---|
| 7.1 模块系统 | 边界与可见性 | mod 树、pub 策略、use 路径 |
| 7.2 Crates 与 Cargo | 依赖与构建 | 清单文件要点、workspace 结构 |
| 7.3 测试与举证 | 行为可信 | 单元测试、集成测试、文档测试 |
先决条件
- 前六章全部基础；有一个能 cargo run 的项目环境。
往下走到哪
模块与测试就位后，第 8 章并发法庭将大量使用"测试证明无竞争"的思路；workspace 是多数真实仓库的最终形态。
本章判例速查
| 报错/现象 | 案情 | 修法方向 |
|---|---|---|
| E0432 | use 路径解析失败 | 补 crate:: 前缀或检查文件归属 |
| E0603 | 项不可见（私有） | 按需 pub / pub(crate) / pub(super) |
| 找不到隔壁文件的函数 | bin 与 lib 是两个 crate | 经包名 use，或并入 lib |
| 测试没被跑到 | 文件不在 cargo 目标内 | 移到 tests/ 或加 #[cfg(test)] |
工程化最低配清单
新项目的工程基线建议一次配齐，后补成本远高于首发：rustfmt.toml 定格式；CI 里三连——cargo fmt --check、cargo clippy -- -D warnings、cargo test；集成测试目录留一个冒烟用例；特性开关只在真有裁剪需求时引入。这套基线约束的不是风格，而是把"机器能审的交给机器"，人力审阅才有余量看设计。
与下一章的衔接
本章的模块边界与测试体系在下一章迎来最严格的验收场景：并发。共享状态的测试要覆盖交错执行，线程泄漏要靠 join 纪律保证，Send/Sync 约束的报错也需要测试来复现——工程纪律与并发安全是同一件事的两面。
工程验收清单
本章的产出验收按四步走：cargo fmt --check 零输出；cargo clippy -- -D warnings 零告警；cargo test 三类测试全绿；cargo doc 无 broken intra-doc link 警告。四条命令写进 CI 脚本后，人工审阅的精力才真正解放到设计层。另一个建议是尽早引入 cargo audit 之类依赖漏洞扫描——依赖是负债这个命题在安全维度上最具体。
三道自测题
一问：集成测试为什么只能访问 pub API？答：tests/ 目录是独立 crate，链接的是库的公开面——顺带充当 API 可用性审查。二问：workspace 共享什么、不共享什么？答：共享 lock 与 target，各成员保有独立 manifest 与版本号。三问：#[cfg(test)] 的作用机制？答：条件编译，测试配置下才编入，正式产物零残留。三题过线即可进入并发庭，工程章的两条主线——边界与举证——此后每个项目都在复用。
收束清单
工程章交付三件可持续的资产：一条 CI 流水线（fmt、clippy、test 三连）、一棵边界清晰的模块树、一套按席位分工的测试。三者都随代码库生长而非腐化——流水线拦截口味漂移，模块边界约束耦合蔓延，测试守护行为契约。带着这三件资产进入并发庭，第 8 章的所有判例才有落地的载体。