第2章 使用 Cargo 管理项目

先做预测

先回答：示例能够编译并运行，是否已经证明设计正确？不能。编译成功只说明当前程序满足类型与语法约束，还要验证输入边界、失败路径、资源生命周期、并发或外部系统条件。是本章的起点，则把起点放进可重复的工程过程。

原书章节骨架

Packt 官方目录把本章组织为包管理器、模块与可见性、Cargo 与 crate、Cargo 扩展与工具、imgtool 项目。这里保留原书问题顺序，再把2019年前后的案例放到当前Rust工程语境中理解：概念不因crate版本变化而失效，但命令、依赖和框架API必须以当前项目锁定版本的官方文档为准。

官方核心单元核对：包管理器；模块与可见性；Cargo与crate；Cargo扩展与工具；Rust开发环境；imgtool项目。

不是孤立语法。它承接包管理器给出的目标，并通过模块与可见性进入真实项目。阅读代码时要沿着输入、所有权或状态、动作、结果和证据五个节点追踪，而不是只记函数名。

[package]
name = "imgtool"
version = "0.1.0"
edition = "2021"
 
[dependencies]
image = "0.25"

机制一：从类型到行为

包管理器把依赖解析、版本约束、制品缓存和发布元数据变成可复现流程；锁文件与清单承担不同责任，库和应用对锁定策略也不同。 模块树组织名称和隐私边界，pub只开放必要接口；文件布局是模块结构的载体，不应让目录偶然决定公共API。 两者协作时，先写出谁拥有数据、谁可以修改、失败由谁处理，再决定具体API。这样可以把编译器诊断还原为契约冲突，而不是把错误信息当成需要逐条消除的噪声。

进一步约束运行行为。它说明“类型正确”与“协议正确”是两层证据：前者由编译器帮助证明，后者还需要测试、时间线和边界输入。

pub mod resize;
 
pub struct Job<'a> {
    pub input: &'a std::path::Path,
    pub output: &'a std::path::Path,
}

机制二：失败、资源与边界

package是Cargo管理单元，crate是编译单元，target是库、二进制、示例或测试目标；先分清三者才能解释一次构建究竟产出什么。 cargo fmt、clippy、metadata和自定义子命令共享项目模型；工具必须读取结构化元数据，不能靠猜测target目录或解析人类输出工作。 失败实验至少覆盖正常、空值或零长度、上限附近、显式错误和资源中断。涉及线程、网络、数据库、GUI或FFI时，还要加入超时、取消、部分完成与关闭路径。

不要把原书示例的依赖版本直接复制到新项目。先固定Rust edition与最小支持版本，再查询维护中的crate文档和迁移说明；保留原书要讲的架构边界，按当前API重写适配层。

cargo check --all-targets
cargo test
cargo metadata --format-version 1

机制三：可复现证据

负责把本章收束成证据。原书的imgtool把清单、模块、依赖、命令行和图像处理连成项目；验收要覆盖输入格式、输出路径、失败原子性与重复执行。 一次可靠验收要保存输入、工具链、依赖锁定、命令、退出状态、关键输出和失败样本。性能结论还要记录release构建、样本数与环境噪声；并发结论则要记录任务边界、超时和关闭结果。

验收清单

1. 在隔离目录运行三段示例，先预测结果和所有权变化，再记录实际编译诊断。
2. 为主路径增加一个正常测试和至少三个边界测试，错误断言检查类别与上下文，而不只匹配整段文本。
3. 清理构建产物后重跑，确认没有依赖本地缓存、环境变量或未声明工具。
4. 若章节涉及外部系统，使用本地测试服务或临时数据库，设置时间预算并验证资源最终释放。

常见误区

本章回顾

本章按照官方目录逐项覆盖包管理器、模块与可见性、Cargo 与 crate、Cargo 扩展与工具、imgtool 项目。核心方法是先用类型表达资源与能力，再用运行期协议约束超时、顺序和外部失败，最后用测试、日志或调试记录证明结果可重复。

术语表