[TOC]
Rust中使用模块组织代码
Rust中的模块化编程
自上个世纪 90 年代以来，软件工程的复杂性越来越高，程序渐渐从一个人的独狼开发转为多人团队协作开发。在今天，通过 Github 或中心化的代码分发网站，我们可以轻松的在一个软件工程中同时引入世界各地的开发者开发的代码，我们与同事在同一个工程目录下并行开发不同的程序功能，或者在不拷贝代码的前提下将一个工程中的代码在另一个工程中复用。这一切都是因为模块化编程。
模块化编程，是强调将计算机程序的功能分离成独立的和可相互改变的“模块”的软件设计技术，它使得每个模块都包含着执行预期功能的一个唯一方面所必需的所有东西，复杂的系统被分割为小块的独立代码块。
Rust 项目的代码组织包含以下三个基本概念：
- Package（包）
- Crate（箱）
- Module（模块）
Package
Package 用于管理一个或多个 Crate。创建一个 Package 的方式是使用 cargo new，我们来看看一个 Package 包含哪些文件。
$ cargo new my-project
Created binary (application) `my-project` package
$ ls my-project
Cargo.toml
src
$ ls my-project/src
main.rs
当我们输入命令时，Cargo 创建了一个目录以及一个 Cargo.toml 文件，这就是一个 Package。默认情况下，src/main.rs 是与 Package 同名的二进制 Crate 的入口文件，因此我们可以说我们现在有一个 my-project Package 以及一个二进制 my-project Crate。同样，如果在创建 Package 的时候带上 --lib，那么 src/lib.rs 将是它的 Crate 入口文件，且它是一个库 Crate。
如果我们的 src 目录中同时包含 main.rs 和 lib.rs，那么我们将在这个 Package 中同时得到一个二进制 Crate 和一个库 Crate，这在开发一些基础库时非常有用，例如你使用 Rust 中实现了一个 MD5 函数，你既希望这个 MD5 函数能作为库被别人引用，又希望你能获得一个可以进行 MD5 计算的命令行工具：那就同时添加 main.rs 和 lib.rs 吧！
Crate
Crate 是 Rust 的最小编译单元，即 Rust 编译器是以 Crate 为最小单元进行编译的。Crate 在一个范围内将相关的功能组合在一起，并最终通过编译生成一个二进制或库文件。例如，我们在上一章中实现的猜数字游戏就使用了 rand 依赖，这个 rand 就是一个 Crate，并且是一个库的 Crate。
Module
Module 允许我们将一个 Crate 中的代码组织成独立的代码块，以便于增强可读性和代码复用。同时，Module 还控制代码的可见性，即将代码分为公开代码和私有代码。公开代码可以在项目外被使用，私有代码则只有项目内部的代码才可以访问。定义一个模块最基本的方式是使用 mod 关键字：
mod mod1 {
pub mod mod2 {
pub const MESSAGE: &str = "Hello World!"
// ...
}
// ...
}
fn main() {
println!(mod1::mod2::MESSAGE);
}
使用pub改变可见性
Rust 中模块内部的代码，结构体，函数等类型默认是私有的，但是可以通过 pub 关键字来改变它们的可见性。通过选择性的对外可见来隐藏模块内部的实现细节。
比较常用的三种 pub 写法：
- pub：成员对模块可见
- pub（self）：成员对模块内的子模块可见
- pub（crate）：成员对整个 crate 可见
如果不使用 pub 声明，成员默认的可见性是私有的：
mod mod1 {
pub const MESSAGE: &str = "Hello World!";
const NUMBER: u32 = 42;
pub(self) fn mod1_pub_self_fn() {
println!("{}", NUMBER);
}
pub(crate) enum CrateEnum {
Item = 4,
}
pub mod mod2 {
pub const MESSAGE: &str = "Hello World!";
pub fn mod2_fn() {
super::mod1_pub_self_fn();
}
}
}
fn main() {
println!("{}", mod1::MESSAGE);
println!("{}", mod1::mod2::MESSAGE);
mod1::mod2::mod2_fn();
println!("{}", mod1::CrateEnum::Item as u32);
}
结构体的可见性
结构体中的字段和方法默认是私有的，通过加上 pub 修饰语可使得结构体中的字段和方法可以在定义结构体的模块之外被访问。要注意，与结构体同一个模块的代码访问结构体中的字段和方法并不要求该字段是可见的：
mod mod1 {
pub struct Person {
pub name: String,
nickname: String,
}
impl Person {
pub fn new(name: &str, nickname: &str) -> Self {
Person {
name: String::from(name),
nickname: String::from(nickname),
}
}
pub fn say_nick_name(&self) {
println!("{}", self.nickname);
}
}
}
fn main() {
let p = mod1::Person::new("jack", "baby");
println!("{}", p.name);
// println!("{}", p.nickname); // 不能访问 nickname
p.say_nick_name();
}
使用use绑定模块成员
正常情况下当我们试图从模块内中访问其成员时，需要输入完整的路径，例如使用 std::fs::read 从磁盘上读取文件：
fn main() {
let data = std::fs::read("src/main.rs").unwrap();
println!("{}", String::from_utf8(data).unwrap());
}
可以使用 use 关键词将完整路径绑定到一个新的名称，这可以减少重复代码：
use std::fs;
fn main() {
let data = fs::read("src/main.rs").unwrap();
println!("{}", String::from_utf8(data).unwrap());
}
可以使用 as 关键字将导入绑定到一个其他名称，它通常用在有多个不同模块都定义了相同名字的成员时使用：
use std::fs as stdfs;
fn main() {
let data = stdfs::read("src/main.rs").unwrap();
println!("{}", String::from_utf8(data).unwrap());
}
使用super与self简化模块路径
除了使用完整路径访问模块内的成员，还可以使用 super 与 self 关键字相对路径对模块进行访问：
- super：上层模块
- self：当前模块
当上层模块，当前模块或子模块中拥有相同名字的成员时，使用 super 与 self 可以消除访问时的歧义：
fn function() {
println!("function");
}
pub mod mod1 {
pub fn function() {
super::function();
}
pub mod mod2 {
fn function() {
println!("mod1::mod2::function");
}
pub fn call() {
self::function();
}
}
}
fn main() {
mod1::function();
mod1::mod2::call();
}
项目目录层次结构
将模块映射到文件
使用 mod <路径> 语法，将一个 rust 源码文件作为模块内引入：
src
├── main.rs
└── mod1.rs
mod1.rs：
pub const MESSAGE: &str = "Hello World!";
main.rs：
mod mod1;
fn main() {
println!("{}", mod1::MESSAGE);
}
将模块映射到文件夹
当一个文件夹中包含 mod.rs 文件时，该文件夹可以被作为一个模块：
src
├── main.rs
└── mod1
└── mod.rs
mod1/mod.rs：
pub const MESSAGE: &str = "Hello World!";
main.rs：
mod mod1;
fn main() {
println!("{}", mod1::MESSAGE);
}
