我们先前所练习的 Rust 程序几乎都只是把程序叙述写在 main.rs 文件中,虽然我们已经会使用函数和方法来分割不同功能的程序,但当程序愈写愈多的时候,这样的作法还是会让程序变得难以维护。这时就需要用到 Rust 提供的「模块」系统了。

模块的使用方式就跟我们撰写函数的方式差不多,我们可以将类似功能的不同函数、方法和其所使用到的结构体、枚举包装成相同的模块。模块就是一个类型和函数的「命名空间」(namespace),命名空间可以将代码有效区隔开来,不互相影响。模块除了可以将类型和函数群组化之外,还可以决定模块要不要公开给其他项目使用。

模块和程序项目的文件结构有关,让我们从创建程序项目开始吧!以往我们创建 Cargo 程序项目的时候都加了 --bin 参数,让 Cargo 创建出可运行的应用程序项目,但是现在要将其改为 --lib 参数,让 Cargo 创建出函数库的程序项目。

使用以下指令,可以创建出 Cargo 的函数库程序项目 communicator:

cargo new --lib communicator

以 cargo new --lib 创建函数库项目

接着移动工作目录到项目根目录下。由于这个是函数库程序项目,Cargo 并没有在 src 目录中产生 main.rs,取而代之的是,它产生出了一个陌生的 lib.rs,文件内容如下:

pub fn add(left: usize, right: usize) -> usize {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

这段程序我们先不管它,将它留在 lib.rs 文件的最底部。由于现在使用的项目没有 main 函数了,因此不可以使用 cargo run 来运行程序项目。如果要测试代码有没有撰写正确,先使用 cargo check 吧!

我们打算让 communicator 项目处理网络相关的通信问题,一开始我们先使用 mod 关键字来定义出一个名叫 network 的模块,并且在模块内再定义一个 connect 函数。程序如下:

mod network {
    fn connect() {}
}

pub fn add(left: usize, right: usize) -> usize {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

如果要在 network 模块外调用 network 模块中的 connect 函数,需要透过 :: 语法来调用。代码如下:

network::connect();

当然我们也可以使用多个 mod 关键字创建出多个不同的模块。如下:

mod network {
    fn connect() {}
}

mod client {
    fn connect() {}
}

pub fn add(left: usize, right: usize) -> usize {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

network 模块和 client 模块内都有 connect 函数,它们的 connect 函数在使用上不会有冲突。如果要调用 network 模块的 connect 函数,程序叙述就写 network::connect();如果要调用 client 模块的 connect 函数,程序叙述就写 client::connect()。

虽然我们现在正在使用 Cargo 的函数库项目,但「模块」其实也可以被定义在应用程序项目上,并没有限制。此外,模块内也可以再有其它的「子模块」。举例来说:

mod network {
    fn connect() {}

    mod client {
        fn connect() {}
    }
}

pub fn add(left: usize, right: usize) -> usize {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

以上程序有两个不同的 connect 函数,分别是 network::connect 和 network::client::connect。此时模块的组织架构如下:

communicator
 └── network
     └── client

当 communicator 项目作为 crate 被引用到其它项目时,connect 函数的调用方式就变成 communicator::network::connect() 和 communicator::network::client::connect()。当然,目前的代码实际上无法让 network 模块直接被引用到其它项目,还必须与 pub 关键字搭配使用才行,这部份将在之后介绍。

现在虽然我们已经知道怎么将代码用 mod 关键字切成模块了,但如果通通都写在 lib.rs 文件内,累积起来后也是会因太多而难以维护。因此,我们要将模块写在不同的文件内!

先看看以下程序:

mod client {
    fn connect() {}
}

mod network {
    fn connect() {}

    mod server {
        fn connect() {}
    }
}

pub fn add(left: usize, right: usize) -> usize {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

模块的组织架构如下:

communicator
 ├── client
 └── network
     └── server

一步一步进行,把 client、network 和 server 都分到不同的文件中。首先,习惯上,为避免 lib.rs 的内容过多,我们只会在 lib.rs 中留下要定义的模块名称,程序如下:

mod client;

mod network;

pub fn add(left: usize, right: usize) -> usize {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

Cargo 在编译函数库项目的时候会先来看 lib.rs 文件,当它发现 lib.rs 文件有定义模块名称却未实作的时候,会有以下两种情形发生:

1. 如果同目录中有 模块名称.rs 文件的话,就会引用进来。
2. 如果同目录中有 模块名称 目录,且同目录中没有 模块名称.rs 文件的话,就会引用 模块名称 目录中的 mod.rs 文件。

如果第一种和第二种情形同时发生,会编译错误。我们让 client 模块用第一种方式引用进来,而 network 则用第二种方式。引用的情形会像是底下这个样子:

mod client {
    // content from src/client.rs
}

mod network {
    // content from src/network/mod.rs
}

pub fn add(left: usize, right: usize) -> usize {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

在 lib.rs 文件中定义要使用的模块名称后,在同样的 src 目录中创建出 client.rs 文件,内容如下:

fn connect() {}

这里要注意的是,用源代码文件将模块的代码分开之后,该模块的源代码文件中就不用再写 mod 关键字了。换句话说就是,因为 client.rs 已经定义了这支程序是一个名为 client 的模块,我们就不再需要写 mod client {} 来定义这个模块内的东西。

到这里我们已经完成 client 模块的部份,接下来看看 network 模块和其子模块 server 要怎么做吧!

在 src 目录中创建 network 目录,并在 network 目录中创建 mod.rs 文件,内容如下:

fn connect() {}

mod server;

注意程序第 3 行,我们又再度使用 mod 关键字定义模块名称,而不将它实作出来,所以又要按照刚才提到的那两个规则引用其它文件啦!

由于 server 模块并没有子模块,因此我们可以直接在目前的 network 目录中再创建 server.rs 文件,内容如下:

fn connect() {}

如此一来就已经成功将所有模块分散到不同文件了!

实际上用第一种方式来创建模块也可以让它拥有子模块,只需要在旁边创建出与该模块同名的目录,并在该目录中放置子模块的源代码文件即可,不过要注意的是不要使用到 mod.rs 这个文件名。不过通常我们还是会直接使用第二种,也就是目录的方式来设计模块和它的子模块,因为这样结构会比较清楚。例如刚才的练习的 client 模块,因为现在它并没有用到子模块,因此我们可以直接在 src 目录下创建 client.rs 文件来实作它。

尝试使用 cargo check 检查目前的 communicator 项目,编译虽然成功,但是有这个警告消息 function `connect` is never used。

connect 函数未被使用的警告消息

这是因为目前三个模块中的 connect 函数,都是私有的状态,且也没有被调用过任何一次。为了解决这个警告,且让引用这个 communicator 项目的项目也能使用这三个模块中的 connect 函数,我们必须使用 pub 关键字,将 connect 函数的访问权限设为公开的。用 pub 关键字将程序修改如下:

pub fn connect() {}
pub fn connect() {}

mod server;
pub fn connect() {}

重新使用 cargo check 编译程序项目,编译虽然成功,但会发现刚才的警告消息 function `connect` is never used 依然存在,这是因为如果我们不将子模块和模块也都设为公开的话,子模块外和 communicator 项目外根本还是没有办法调用到三个模块中的 connect 函数。

将函数设为 pub 后仍有的警告

用 pub 关键字将程序修改如下:

pub fn connect() {}

pub mod server;
pub mod client;

pub mod network;

pub fn add(left: usize, right: usize) -> usize {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

修改后再次使用 cargo check 编译程序项目,编译成功,警告消息也没了!

加上 pub 后编译成功没有警告

没有使用 pub 关键字设置为公开的模块、函数、类型等项目都会被当作是私有的,而私有的项目就只有在该模块底下或是该模块的子模块才能访问。另外,使用 use 关键字将命名空间加入至目前程序的 scope,其命名空间内的公开资源对于目前程序的 scope 来说是私有的,如非在 use 关键字前也加上 pub 关键字。举例来说:

mod outermost {
    pub fn middle_function() {}

    fn middle_secret_function() {}

    mod inside {
        pub fn inner_function() {}

        fn secret_function() {}
    }
}

fn try_me() {
    outermost::middle_function();
    outermost::middle_secret_function();
    outermost::inside::inner_function();
    outermost::inside::secret_function();
}

以上程序,第 15、16、17 进程式会编译错误。第 15 进程式因为 middle_secret_function 函数不是公开的所以编译错误,而第 16、17 进程式因为 inside 子模块不是公开的所以编译错误。

若将 inside 子模块加上 pub 关键字改为公开的,程序如下:

mod outermost {
    pub fn middle_function() {}

    fn middle_secret_function() {}

    pub mod inside {
        pub fn inner_function() {}

        fn secret_function() {}
    }
}

fn try_me() {
    outermost::middle_function();
    outermost::middle_secret_function();
    outermost::inside::inner_function();
    outermost::inside::secret_function();
}

第 16 进程式会编译成功,而第 17 进程式则因为 secret_function 函数不是公开的,所以编译错误。

将第 15 行和第 17 进程式先注解掉,程序如下:

mod outermost {
    pub fn middle_function() {}

    fn middle_secret_function() {}

    pub mod inside {
        pub fn inner_function() {}

        fn secret_function() {}
    }
}

fn try_me() {
    outermost::middle_function();
    // outermost::middle_secret_function();
    outermost::inside::inner_function();
    // outermost::inside::secret_function();
}

既然刚才提到私有项目可以给子模块使用,那如果我们想在 inner_function 函数中调用 middle_secret_function 函数,有办法做到吗?程序叙述直接写 middle_secret_function()?

mod outermost {
    pub fn middle_function() {}

    fn middle_secret_function() {}

    pub mod inside {
        pub fn inner_function() {
            middle_secret_function();
        }

        fn secret_function() {}
    }
}

fn try_me() {
    outermost::middle_function();
    // outermost::middle_secret_function();
    outermost::inside::inner_function();
    // outermost::inside::secret_function();
}

以上程序第 8 行,我们直接将程序叙述写成 middle_secret_function(),却造成编译错误,这是因为我们必须要把命名空间写清楚,指定是要调用哪里的 middle_secret_function 函数。程序改写如下:

mod outermost {
    pub fn middle_function() {}

    fn middle_secret_function() {}

    pub mod inside {
        pub fn inner_function() {
            crate::outermost::middle_secret_function();
        }

        fn secret_function() {}
    }
}

fn try_me() {
    outermost::middle_function();
    // outermost::middle_secret_function();
    outermost::inside::inner_function();
    // outermost::inside::secret_function();
}

以上程序可以编译成功。程序第 8 行,直接以 crate:: 语法开头来指定命名空间,代表要从目前这个程序的 crate 开始算起;crate::outermost 代表要指定使用目前这个程序的 crate 底下的 outermost 模块。

此外,也可以利用 super 关键字来指定回到上一层的命名空间,程序改写如下:

mod outermost {
    pub fn middle_function() {}

    fn middle_secret_function() {}

    pub mod inside {
        pub fn inner_function() {
            super::middle_secret_function();
        }

        fn secret_function() {}
    }
}

fn try_me() {
    outermost::middle_function();
    // outermost::middle_secret_function();
    outermost::inside::inner_function();
    // outermost::inside::secret_function();
}

以上程序可以编译成功。程序第 8 行,super:: 表示要使用 inside 模块的上一层命名空间,也就是 outermost。

除了 crate:: 和 super:: 语法之外,我们也可以直接以 :: 开头。在 Rust 2015 的版本中,:: 的功能和 crate:: 是一样的,但是在 Rust 2018 的版本中,:: 的功能只能够用来引用外部 crate 下的项目。

完成我们的函数库程序项目后,该怎么将它引用至可运行应用程序项目中呢?继续拿刚才完成的 communicator 函数库程序项目来举例,我们先用 Cargo 产生一个可运行的应用程序项目 communicator_exe,指令如下:

cargo new --bin communicator_exe

创建 communicator_exe 应用程序项目

编辑 communicator_exe 程序项目的 Cargo.toml 设置档,在 dependencies 区块加入 communicator 程序项目的设置,如下:

[package]
name = "communicator_exe"
version = "0.1.0"
edition = "2021"

[dependencies]
communicator = { path = "../communicator" }

此时,若要在 communicator_exe 项目中调用 communicator 项目下的 network::server::connect() 函数,程序如下:

fn main() {
    communicator::network::server::connect();
}

这边要注意的是,如果函数库程序项目的名称,也就是在函数库程序项目里的 Cargo.toml 设置档写的项目名称为 communicator 的话,在被其它项目引用时,Cargo.toml 也要使用相同的名称,不能随意更改。但如果要更改的话,可以在 Cargo.toml 的 dependencies 区块中使用 package 选项来指定要相依的套件名称(该函数库原本的名称),如此一来我们就可以自订要用什么名称来表示该函数库了。如下设置,在 communicator_exe 项目中,可以使用 com 这个名称来表示 communicator 函数库项目。

[package]
name = "communicator_exe"
version = "0.1.0"
edition = "2021"

[dependencies]
com = { package = "communicator", path = "../communicator" }

如此一来,若要在 communicator_exe 项目中调用 communicator::network::server::connect() 函数,就变成要写成 com::network::server::connect()。如下:

fn main() {
    com::network::server::connect();
}

我们也可以利用 use 关键字和 as 关键字在特定 scope 下改变 crate、函数、类型等项目的名称。

例如:

use communicator as com;

fn main() {
    com::network::server::connect();
}

即便我们利用上面的方式将代码稍微缩短了,但 com::network::server::connect() 这样的语法还是很长,不太好写。这时可以考虑利用 use 关键字,将指定命名空间下的函数、类型等项目加入至目前程序的 scope。举例来说:

use communicator as com;

use com::client;
use com::network;

use network::server;

fn main() {
    server::connect();
}

use 关键字可以搭配 {} 语法使用,可以一次将某个命名空间下的多个项目加进程式。举例来说:

use communicator as com;

use com::{client, network};

use network::server;

fn main() {
    server::connect();
}

也支持嵌套用法。举例来说:

use communicator as com;

use com::{client, network, network::server};

fn main() {
    server::connect();
}

use 关键字甚至能直接使用星号 *,来表示某个命名空间下的所有项目。举例来说:

use communicator as com;

use com::*;

use network::*;

fn main() {
    server::connect();
}

最后我们来看一下 communicator 程序项目的 lib.rs,在一开始我们忽略的由 Cargo 自动产生出来的 tests 模块。程序如下:

pub mod client;

pub mod network;

pub fn add(left: usize, right: usize) -> usize {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

我们之前都忽略了 lib.rs 中的 tests,将其考虑进来后,communicator 程序项目的组织架构如下:

communicator
 ├── client
 ├── network
 |   └── server
 └── tests

因为有在 tests 模块定义前使用 #[cfg(test)],因此这个 tests 模块只会在我们使用 cargo test 来测试程序项目的时候才会被用到。当然 tests 模块的名称其实不一定要叫作 tests。这个加上 #[cfg(test)] 定义出来的模块,就像是一个拥有许多测试案例的函数集合,定义在这个模块中的函数,如果再加上 #[test] 的话,在使用 cargo test 来测试程序项目的时候,该函数就会被运行。

所以现在我们的 communicator 程序项目,使用 cargo test 进行测试的结果如下图:

以 cargo test 测试 communicator 项目

我们可以在 tests 模块中,搭配 use 关键字来将我们要测试的其它模块加入至 tests 模块的 scope,方便进行测试。修改后的程序如下:

pub mod client;

pub mod network;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        client::connect();
        network::connect();
        network::server::connect();
    }
}

有关于更详细的程序项目测试方式,会在之后的章节作介绍。

总结

学习完这个章节的内容后,我们已经有能力组织管理我们的 Rust 代码,甚至还可以将我们撰写的函数库程序项目分享给其他人使用了。在接下来的章节,我们要来学习 Rust 编程语言内置的 Vec、HashMap 等常用的集合数据结构。

下一章:常用的集合。