3.1 package：Cargo 管理的项目单元#

一个 package 通常就是一个带 Cargo.toml 的目录：

1
hello-rust/
2
├── Cargo.toml
3
└── src/
4
    └── main.rs

Cargo.toml 描述这个 package 的名字、版本、edition、依赖、feature、构建配置等：

1
[package]
2
name = "hello-rust"
3
version = "0.1.0"
4
edition = "2024"
5

6
[dependencies]
7
anyhow = "1"

package 是 Cargo 看项目的单位，也是发布到 crates.io 时的单位。更准确地说，crates.io 上发布的是一个 package 的某个版本，虽然日常口语里大家经常说”发布一个 crate”。

严格说，不是所有带 Cargo.toml 的目录都是 package。如果根 Cargo.toml 只有 [workspace]，没有 [package]，那它只是 workspace 根目录，不是一个可被单独构建和发布的 package。真正的 package 要有自己的 [package] 表。

3.2 target：Cargo 要构建的目标#

在 Cargo 项目里，不是先问”这个文件夹是不是一个 crate”，而是先问：这个 package 里有哪些 target？

target 是 Cargo 要构建的目标。常见 target 有：

• library target：构建出一个 library crate，给其他 crate 依赖。一个 package 最多只能有一个 library target。
• binary target：构建出一个 binary crate，最后生成可执行文件。一个 package 可以有多个 binary target。
• example target：示例程序。
• test target：集成测试程序。
• bench target：benchmark 程序。

每个 target 都有一个 crate root，也就是这个 crate 的入口文件。crate root 是一个具体的 .rs 文件，不是文件夹。例如 src/lib.rs、src/main.rs、src/bin/convert.rs 都可以是 crate root；src/、src/bin/、crates/core/ 这些目录本身不是 crate root。

Cargo 根据默认目录约定自动发现 target，也可以在 Cargo.toml 里显式配置每个 target 的 root 文件。

默认约定是：

也可以不按默认文件名，而是在 Cargo.toml 里显式写：

1
[lib]
2
name = "image_tool"
3
path = "src/library.rs"
4

5
[[bin]]
6
name = "resize"
7
path = "src/tools/resize.rs"
8

9
[[bin]]
10
name = "inspect"
11
path = "src/tools/inspect.rs"

这个配置的意思是：

• library target 的 crate root 是 src/library.rs。
• resize 这个 binary target 的 crate root 是 src/tools/resize.rs。
• inspect 这个 binary target 的 crate root 是 src/tools/inspect.rs。

所以，crate 的边界不是由文件夹天然决定的，而是由 target 的 crate root 文件决定起点，再由这个 root 文件里声明的模块树继续扩展。

3.3 crate：一次编译的代码单元#

crate 是 rustc 的编译单元。Cargo 发现一个 target 后，会把这个 target 交给 rustc 编译；从 rustc 角度看，这个 target 就是一个 crate。

crate 的类型由 target 类型决定：

• library target 编译成 library crate。
• binary target 编译成 binary crate。
• example、integration test、bench 也会各自作为独立 crate 编译，只是用途不同。

这里说的 library / binary，是 Cargo target 层面的分类。[lib] 里还可以用 crate-type 控制库的产物格式，例如 rlib、cdylib、staticlib；那是同一个 library target 生成什么格式的问题，不是”一个 package 有多个 library target”。

例如：

1
image-tool/
2
├── Cargo.toml
3
└── src/
4
    ├── lib.rs          # library target 的 crate root，生成 library crate: image_tool
5
    ├── operations.rs   # 被 src/lib.rs 通过 mod 挂进 library crate
6
    ├── main.rs         # 默认 binary target 的 crate root
7
    └── bin/
8
        ├── resize.rs   # resize binary target 的 crate root
9
        └── inspect.rs  # inspect binary target 的 crate root

这里不是”一个文件夹就是一个 crate”。更准确地说，这个 package 里有四个 target，因此会编译出四个 crate：

src/main.rs、src/bin/resize.rs、src/bin/inspect.rs 是三个彼此独立的 binary crate root。它们不会自动共享彼此的模块，也不能用 use 去引用另一个 binary target。

如果有共用逻辑，通常放到 src/lib.rs 对应的 library crate 里，然后这些 binary crate 像依赖普通库一样依赖这个 library crate。

例如 package 名字是 image-tool，library crate 在代码里的名字通常是 image_tool。src/lib.rs 可以这样暴露公共模块：

1
pub mod operations;

1
pub fn resize_image(input: &str) {
2
    println!("resize {input}");
3
}

然后 binary target 里可以引用 image_tool 这个 library crate：

1
use image_tool::operations::resize_image;
2

3
fn main() {
4
    resize_image("cat.png");
5
}

也就是说，同一个 package 里的 binary target 要引用本 package 的 library crate，也从这个 library crate 的名字开始写。默认情况下，这个名字来自 package 名：image-tool 这个 package 的 library crate 名通常是 image_tool，所以 binary 里写 use image_tool::...。

但在 src/lib.rs 以及它下面的 library 模块内部，引用本 library crate 自己的其他模块时，通常写 crate::...：

1
use crate::config::ImageConfig;

注意，这里的 image_tool 不是 binary target，而是 package 里的 library crate；operations 也不是 binary target，而是 library crate 里通过 pub mod operations; 暴露出来的模块。src/bin/resize.rs 这个 binary target 只是一个可执行入口，它不会变成可被 use image_tool::resize 引用的库模块。

package 名字可以带短横线，比如 image-tool；默认 library crate 名在代码里通常会转成下划线，也就是 image_tool。binary target 名则用于运行可执行程序，例如：

1
cargo run --bin resize

3.4 lib 和 bin target 的数量限制#

Cargo 对 library target 和 binary target 的数量限制不同。规则本身很简单：

也就是说：

• 一个 package 可以没有 library target。
• 一个 package 可以有一个 library target。
• 一个 package 不能有两个 library target。
• 一个 package 可以有零个、一个或多个 binary target。

1
[dependencies]
2
image-tool = "0.1"

1
use image_tool::operations::resize_image;

1
my-product/
2
├── Cargo.toml
3
└── crates/
4
    ├── core/      # 一个 package，一个 lib
5
    ├── storage/   # 一个 package，一个 lib
6
    └── api/       # 一个 package，一个 lib

1
[lib]
2
crate-type = ["rlib", "cdylib"]

1
fn main() {
2
    println!("run database migration");
3
}

1
fn main() {
2
    println!("run admin command");
3
}

3.5 module：crate 内部的命名空间#

module 是 crate 里的代码组织和可见性边界。它不是 Cargo 的发布单位，也不是 rustc 的独立编译单位。

一个 crate 到底包含哪些 .rs 文件？答案是：从这个 crate 的 crate root 文件出发，所有被 mod 声明挂进模块树的文件，才属于这个 crate。

这不等于所有 .rs 文件都必须直接放在 src/ 下面。src/ 只是默认 target root 的常见目录；模块可以继续嵌套到子目录里。模块查找大致遵循两层关系：

• crate root 由 target 决定，例如 src/lib.rs、src/main.rs、src/bin/resize.rs。
• 子模块文件的位置由声明它的父模块决定，例如 src/lib.rs 里的 mod db; 会找 src/db.rs 或 src/db/mod.rs，而 src/db.rs 里的 mod model; 会找 src/db/model.rs。

例如下面这个结构里，model.rs 不在 src/ 第一层，但它仍然属于当前 library crate：

1
src/
2
├── lib.rs
3
├── db.rs
4
└── db/
5
    └── model.rs

1
mod db;

1
mod model;

这里的模块树是 crate -> db -> model。目录只是模块文件的存放位置；真正决定文件是否进入 crate 的，仍然是从 crate root 开始的一连串 mod 声明。

最小例子：

1
mod image;
2

3
pub fn run() {
4
    image::load();
5
}

1
pub fn load() {
2
    println!("load image");
3
}

mod image; 的意思是：在当前 crate 里声明一个名为 image 的模块，模块内容从 src/image.rs 读取。

关键点是：Rust 不会因为文件存在就自动把它编进项目。一个 .rs 文件必须通过 crate root 或其他模块里的 mod xxx; 挂到模块树上，才是当前 crate 的一部分。

例如目录里有一个没有被 mod 引用的文件：

1
src/
2
├── lib.rs
3
├── image.rs
4
└── unused.rs

1
mod image;

这里 image.rs 属于当前 library crate，unused.rs 不属于。它只是一个躺在目录里的文件，编译器不会自动读取它。

这和 C++ 很不一样。C++ 常见组织方式是 .h 声明、.cpp 实现、构建系统决定哪些 .cpp 参与编译；Rust 则是从 crate root 出发，用 mod 形成一棵模块树。

这几个概念的关系可以这样理解：

5.1 use 不负责加载文件#

看这个例子：

1
mod db;
2

3
use db::User;
4

5
pub fn create_user() -> User {
6
    User::new("Alice")
7
}

mod db; 才是把 db 模块加入当前 crate 的动作。use db::User; 只是让后面可以直接写 User，不用每次写 db::User。

如果删掉 use，也可以写成：

1
pub fn create_user() -> db::User {
2
    db::User::new("Alice")
3
}

如果删掉 mod db;，只留下 use db::User;，编译器找不到 db 模块。

5.2 路径从哪里开始？#

Rust 里常见路径有几种：

1
crate::db::User       // 从当前 crate root 开始
2
super::model::User    // 从父模块开始
3
self::helper::parse   // 从当前模块开始
4
db::User              // 相对当前作用域，或来自 extern prelude

外部依赖这里要区分两个名字：

• Cargo.toml 里写的是 dependency 的 package 名。
• Rust 代码里的路径从这个依赖暴露出来的 crate 名开始。

对普通第三方依赖来说，Rust 代码里看到的这个 crate，就是该 package 暴露的唯一 library crate；不是 package 本身，也不是它的 binary target。多数情况下 package 名和 library crate 名一样，所以看起来像是直接从 package 名开始：

1
use serde::{Deserialize, Serialize};
2
use anyhow::Result;

对应的依赖是：

1
[dependencies]
2
serde = { version = "1", features = ["derive"] }
3
anyhow = "1"

但如果 package 名里有短横线，代码里的 crate 名通常会变成下划线。例如 package 名是 image-tool，代码里通常写 image_tool：

1
[dependencies]
2
image-tool = "0.1"

1
use image_tool::operations::resize_image;

也可以在依赖里显式重命名。左边是当前项目里使用的依赖名，也会成为代码里的 crate 名；package 字段才是 registry 上真实的 package 名：

1
[dependencies]
2
img = { package = "image-tool", version = "0.1" }

1
use img::operations::resize_image;

所以更准确地说：Cargo 根据 [dependencies] 里的 package 信息下载和编译依赖；Rust 代码里的 use 路径从可见的 crate 名开始。

同一个 package 内部也是类似规则：binary target 引用本 package 的 library crate 时，从 library crate 名开始；library crate 自己内部引用自身模块时，通常从 crate:: 开始。

use 后面跟的也是一个路径。这个路径最终指向某个 item，例如模块、结构体、函数、trait、枚举变体等。常见写法有：

1
use crate::db::User;                  // 从当前 crate root 开始
2
use super::model::User;               // 从父模块开始
3
use self::helper::parse;              // 从当前模块开始
4
use serde::{Deserialize, Serialize};  // 从外部 crate 名开始
5
use std::collections::HashMap;        // 从标准库 crate 名开始

use 的作用是把路径末尾的名字引入当前作用域，或者用 as 起别名：

1
use crate::db::User;
2
use crate::db::User as DbUser;

它不负责加载文件，也不会绕过可见性检查。也就是说，use crate::db::config::read_pool_config; 能不能写成功，取决于：

• crate::db::config::read_pool_config 这个路径是否真的存在。
• 路径上的 db、config 模块对当前位置是否可见。
• read_pool_config 本身对当前位置是否可见。

5.3 可见性：默认私有，路径逐层公开#

Rust 的 item 默认是私有的。不写 pub 时，item 只能在定义它的模块及其子模块中访问；兄弟模块、父模块和外部 crate 都不能直接访问。

pub 也不是简单的”全局公开”。一个 item 即使写了 pub，外部代码也必须能访问它所在路径上的每一层模块，才能真正用到它。也就是说，Rust 的可见性是沿着模块路径逐层生效的。

常见写法：

这里最容易误解的是”父模块、子模块、兄弟模块”之间的关系。假设模块树是：

1
crate
2
└── db
3
    ├── config
4
    │   ├── load_secret
5
    │   ├── read_pool_config
6
    │   └── sub
7
    └── service

load_secret 定义在 config 里，它的父模块是 config，祖先模块是 db 和 crate。它不是直接属于 db，也不是直接属于 crate。完整路径是：

1
crate::db::config::load_secret

如果不写 pub：

1
mod db {
2
    mod config {
3
        fn load_secret() {}
4

5
        mod sub {
6
            fn verify_child_module_access() {
7
                super::load_secret(); // 可以：sub 是 config 的子模块
8
            }
9
        }
10

11
        fn load_current_module_secret() {
12
            load_secret(); // 可以：就在 config 当前模块里
13
        }
14
    }
15

16
    fn initialize_pool_from_parent() {
17
        // config::load_secret(); // 不可以：db 是 config 的父模块，不是 config 的子模块
18
    }
19
}

这段代码说明两件事：

1. config::sub 可以访问 config::load_secret，因为 sub 是 config 的子模块。
2. db 不能访问 config::load_secret，因为父模块不会自动拥有子模块里的私有 item。

还要注意，“有访问权限”和”名字在当前作用域里”不是一回事。在 sub 里可以访问 load_secret，但通常要写路径：

1
mod config {
2
    fn load_secret() {}
3

4
    mod sub {
5
        fn load_secret_from_child_module() {
6
            // load_secret();       // 名字不在 sub 当前作用域里，通常找不到
7
            super::load_secret();   // 可以：通过父模块路径访问
8
        }
9
    }
10
}

也可以先 use 引入名字：

1
mod config {
2
    fn load_secret() {}
3

4
    mod sub {
5
        use super::load_secret;
6

7
        fn load_imported_secret() {
8
            load_secret(); // 可以：已经用 use 引入当前作用域
9
        }
10
    }
11
}

如果希望 db 或 db 下的兄弟模块 service 也能访问 config 里的函数，就要把可见性扩大到父模块范围：

1
mod db {
2
    mod config {
3
        fn load_secret() {}
4
        pub(super) fn read_pool_config() {}
5
        pub(crate) fn normalize_db_url() {}
6
    }
7

8
    mod service {
9
        fn connect_with_pool_config() {
10
            // super::config::load_secret();      // 不可以：load_secret 只对 config 及其子模块可见
11
            super::config::read_pool_config();    // 可以：read_pool_config 对 db 范围可见
12
            super::config::normalize_db_url();    // 可以：normalize_db_url 对当前 crate 可见
13
        }
14
    }
15

16
    fn initialize_pool() {
17
        // config::load_secret(); // 不可以
18
        config::read_pool_config(); // 可以
19
        config::normalize_db_url(); // 可以
20
    }
21
}

这里 pub(super) 的 super 指的是 config 的父模块，也就是 db。因此 read_pool_config 在 db 这个范围里可见：db 自己可以访问，db::service 这种 db 的子模块也可以访问。

可以画成下面这样：

最后再强调一次路径问题。就算某个 item 写了 pub(crate)，也不代表任何地方都一定能写出它的完整路径；路径上的模块也要能访问。换句话说：

• normalize_db_url 自己允许整个 crate 访问。
• 但如果 config 这个模块路径对某个位置不可见，那仍然不能通过 crate::db::config::normalize_db_url() 访问。
• 常见解决方式是用 pub use 在更合适的模块边界重导出一个稳定路径。

例如：

1
pub struct User {
2
    id: u64,
3
    name: String,
4
}
5

6
impl User {
7
    pub fn new(id: u64, name: String) -> Self {
8
        Self { id, name }
9
    }
10

11
    pub fn name(&self) -> &str {
12
        &self.name
13
    }
14

15
    pub(crate) fn id(&self) -> u64 {
16
        self.id
17
    }
18
}

这里 User 类型公开，new 和 name 公开，但字段 id、name 仍然私有。外部用户必须通过构造函数和方法使用 User，不能随手改字段。

pub(crate) 很适合工程内部 API。例如某个函数需要在 crate 内多个模块共享，但不想暴露给库使用者：

1
pub(crate) fn normalize_email(email: &str) -> String {
2
    email.trim().to_lowercase()
3
}

一个常见设计原则是：模块内部可以乱一点，模块边界要干净；crate 内部可以宽一点，crate 对外 API 要克制。

5.4 pub use：重导出，整理对外 API#

实际工程里不希望使用者知道你的内部文件结构。例如内部是：

1
src/
2
├── lib.rs
3
└── db/
4
    ├── mod.rs
5
    ├── model.rs
6
    └── query.rs

如果直接公开内部路径，用户可能要写：

1
use my_service::db::model::User;
2
use my_service::db::query::find_user;

更好的做法是在 db/mod.rs 里重导出：

1
mod model;
2
mod query;
3

4
pub use model::User;
5
pub use query::find_user;

然后用户只需要：

1
use my_service::db::{find_user, User};

pub use 是 Rust 组织公共 API 很常用的手段。内部文件可以继续拆得很细，对外暴露的路径保持稳定。

10.1 分发可执行程序#

如果是 CLI 或服务端程序，最直接：

1
cargo build --release

产物在：

1
target/release/my-tool

本机安装可以用：

1
cargo install --path .

开源工具常见做法是 CI 为 Linux/macOS/Windows 分别构建 release artifact，再上传到 GitHub Releases。

10.2 发布 library 到 crates.io#

如果是库，发布前通常需要准备好：

• name
• version
• edition
• license
• description
• repository
• readme
• 合理的 public API 和文档注释

示例：

1
[package]
2
name = "my-config"
3
version = "0.1.0"
4
edition = "2024"
5
license = "MIT OR Apache-2.0"
6
description = "A small config loader"
7
repository = "https://github.com/example/my-config"
8
readme = "README.md"

发布前先 dry run：

1
cargo package
2
cargo publish --dry-run

确认没问题后：

1
cargo publish

发布后，别人就可以：

1
[dependencies]
2
my-config = "0.1"

需要注意：crates.io 上已经发布的版本不能覆盖。发现问题后通常是发新版本；如果某个版本不希望新项目继续解析到，可以 cargo yank，但 yank 不会删除已经发布的包，也不会影响已经锁定该版本的项目。

10.3 内部分发#

公司或个人项目内部也可以不走 crates.io：

1
[dependencies]
2
my-lib = { path = "../my-lib" }

或者：

1
[dependencies]
2
my-lib = { git = "ssh://git@example.com/team/my-lib.git", tag = "v1.2.0" }

更正式的组织可以使用私有 registry，或者在 CI 里做 cargo vendor，把依赖源码固定到仓库或构建环境中。