Cargo 命令

Cargo 常用命令速查表

命令	目的	常用场景
`cargo new`	创建新项目	开始一个全新的 Rust 项目
`cargo build`	编译项目	检查代码是否能成功构建
`cargo run`	编译并运行	开发时快速查看程序运行结果
`cargo check`	快速检查错误	只检查语法和类型，不生成可执行文件（最快）
`cargo test`	运行测试	执行单元测试和集成测试
`cargo add`	添加依赖	向 `Cargo.toml`中添加第三方库
`cargo update`	更新依赖	升级依赖包到版本允许的最新的版本
`cargo doc`	生成文档	查看当前项目及其依赖的离线 API 文档
`cargo fmt`	格式化代码	自动统一代码风格
`cargo clippy`	静态分析	查找代码中的潜在问题和不规范写法
`cargo clean`	清理缓存	删除生成的 `target`目录以释放空间
`cargo metadata`	显示项目元数据	查看项目的依赖信息、目标平台等

1. 项目初始化与创建

`cargo new <name>` : 创建一个名为 `<name>` 的目录，包含基本的项目结构（如 `Cargo.toml` 和 `src/main.rs`）

默认创建二进制项目。若要创建库，使用 `--lib` 参数

`cargo init` : 在当前目录下初始化 Rust 项目，而不是创建新文件夹

2. 构建与运行

`cargo build` : 默认进行 Debug 编译，包含调试信息，但运行速度较慢

`cargo build --release` : 进行优化编译，去掉调试信息，生成的程序运行速度最快，适合发布

`cargo run` : 它是 `build` 和执行的组合。如果你修改了代码，它会自动重新编译再运行

3. 依赖包管理

`cargo add <crate>` : 现代 Cargo 版本（1.62+）支持。直接从命令行添加库，例如 `cargo add serde`，会自动修改 `Cargo.toml`

`cargo tree` : 打印出当前项目所有依赖的树状结构，帮助排查版本冲突或依赖过多的问题

4. 测试与文档

`cargo test` : 自动寻找代码中带有 `#[test]` 标记的函数并运行

Rust 的测试主要分为三大类，以下是它们的对比表及详细拆解：

Rust 测试分类速查表

测试类型	存放位置	编写方式	执行命令 (精细化)
单元测试 (Unit)	逻辑代码文件内 (`src/`)	`mod tests` + `#[test]`	`cargo test <模块名>`
集成测试 (Integration)	项目根目录 `tests/` 文件夹	独立 `.rs` 文件	`cargo test --test <文件名>`
文档测试 (Doc)	源代码的文档注释中	/// ```rust ... ```	`cargo test --doc`

a. 单元测试 (Unit Tests) —— 内部测试

位置：直接写在 src/*.rs 文件里。通常为了不影响阅读，会放在文件底部的 mod tests 中。
特点：可以测试**私有(private)**函数。
命令技巧：
cargo test：运行所有测试。
cargo test path::to::module：只运行某个特定模块下的单元测试。
cargo test --lib：只运行库中的单元测试，忽略集成测试。

b. 集成测试 (Integration Tests) —— 外部测试

位置：项目根目录下创建一个 tests/ 目录，里面存放 .rs 文件（例如 tests/common_test.rs）。
特点：

Cargo 会将 tests/ 下的每个文件都编译成一个独立的 Crate（包）。
只能像外部用户一样测试**公开(pub)**接口。
如果你的项目只有 src/main.rs（二进制项目）而没有 src/lib.rs，则无法直接使用 tests/ 目录。

命令技巧：
cargo test --test common_test：只执行 tests/common_test.rs 里的测试。

c. 文档测试 (Doc Tests) —— 示例即测试

位置：写在函数上方的 /// 注释里。
特点：确保你给用户看的示例代码永远能跑通，不会因为代码重构而过时。
命令技巧：
cargo test --doc：专门只跑文档里的示例代码。

d. 常见的过滤与执行参数

当你觉得全量运行太慢时，这些参数非常有用：

按名称过滤：
cargo test login：运行所有函数名包含 “login” 的测试。
多包/工作区 (Workspaces)：
cargo test -p package_name：在大型项目中，只运行某个特定子包的测试。
忽略某些测试：
在代码里标记 #[ignore]。
运行：cargo test -- --ignored（专门跑被忽略的测试）。
隐藏输出/实时查看：
cargo test -- --nocapture：即便测试通过，也把代码里的 println! 打印出来。

`cargo doc --open` : 这是 Rust 最人性化的功能之一。它会提取代码中的文档注释（`///`）并结合依赖库的文档，生成一个精美的本地 HTML 网页并在浏览器中打开

5. 代码质量与规范

`cargo fmt` : 强制执行 Rust 官方代码风格。团队协作时，通过这个命令可以避免因代码格式不一导致的 Git 冲突

`cargo clippy` : 被称为“管家婆”。它不仅检查错误，还会告诉你“这里其实可以用更简洁的写法”，是学习地道 Rust（Idiomatic Rust）的最佳途径

6. 项目结构

命令	目的	常用场景
`cargo metadata`	导出项目元数据 (JSON)	让 IDE、构建脚本或第三方工具读取项目结构
`--no-deps`	仅显示当前项目信息	排除庞大的第三方依赖树，只看本项目的包信息
`--format-version 1`	指定输出格式版本	目前仅支持版本 1，确保工具解析的兼容性

当你运行 cargo metadata 时，Cargo 会解析你的 Cargo.toml 和 Cargo.lock，然后生成一个包含以下信息的巨大 JSON 对象：

工作空间（Workspace）结构：包含哪些成员包（members）。
依赖树：每个依赖包的版本、来源、依赖的其他包等。
目标（Targets）：每个包包含哪些二进制文件（bin）、库（lib）或示例（examples）。
编译路径：各种文件的绝对路径，方便工具直接访问源代码。

输出的 JSON 结构通常如下：

{
  "packages": [ ... ],       // 所有包的详细信息
  "workspace_members": [ ... ], // 工作区成员的 ID
  "resolve": {               // 依赖图（谁依赖了谁）
    "nodes": [ ... ]
  },
  "target_directory": "...", // 编译输出目录的路径
  "version": 1               // 元数据格式版本
}

Keyboard shortcuts

Rust study