Rust从入门到实战系列一百五十九：使用 pub use 导出合适的公有 API

第七章介绍了如何使用 mod 关键字来将代码组织进模块中，如何使用 pub 关键字将项变为公
有，和如何使用 use 关键字将项引入作用域。然而你开发时候使用的文件架构可能并不方便用
户。你的结构可能是一个包含多个层级的分层结构，不过这对于用户来说并不方便。这是因为想
要使用被定义在很深层级中的类型的人可能很难发现这些类型的存在。他们也可能会厌烦要使用
use my_crate::some_module::another_module::UsefulType; 而不是 use my_crate::UsefulType; 来
使用类型。
公有 API 的结构是你发布 crate 时主要需要考虑的。crate 用户没有你那么熟悉其结构，并且如果模块层
级过大他们可能会难以找到所需的部分。
好消息是，即使文件结构对于用户来说 不是很方便，你也无需重新安排内部组织：你可以选择使用
pub use 重导出（re-export）项来使公有结构不同于私有结构。重导出获取位于一个位置的公有项并将
其公开到另一个位置，好像它就定义在这个新位置一样。
例如，假设我们创建了一个描述美术信息的库 art。这个库中包含了一个有两个枚举 PrimaryColor 和
SecondaryColor 的模块 kinds，以及一个包含函数 mix 的模块 utils，如示例 14-3 所示：
文件名: src∕lib.rs
//! # Art
//!
//! A library for modeling artistic concepts.
pub mod kinds {
/// The primary colors according to the RYB color model.
pub enum PrimaryColor {
Red,
Yellow,
Blue,
}
/// The secondary colors according to the RYB color model.
pub enum SecondaryColor {
Orange,
Green,
Purple,
}
}
pub mod utils {
use crate::kinds:😗;
/// Combines two primary colors in equal amounts to create
/// a secondary color.
pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
// --snip–

unimplemented!();

}
}
示例 14-3：一个库 art 其组织包含 kinds 和 utils 模块
cargo doc 所生成的 crate 文
包含 kinds 和 utils 模块的库 art 的文档首页
注意 PrimaryColor 和 SecondaryColor 类型、以及 mix 函数都没有在首页中列出。我们必须点击 kinds
或 utils 才能看到他们。
另一个依赖这个库的 crate 需要 use 语句来导入 art 中的项，这包含指定其当前定义的模块结构。示例
14-4 展示了一个使用 art crate 中 PrimaryColor 和 mix 项的 crate 的例子：
文件名: src∕main.rs
use art::kinds::PrimaryColor;
use art::utils::mix;
fn main() {
let red = PrimaryColor::Red;
let yellow = PrimaryColor::Yellow;
mix(red, yellow);
}
示例 14-4：一个通过导出内部结构使用 art crate 中项的 crate
示例 14-4 中使用 art crate 代码的作者不得不搞清楚 PrimaryColor 位于 kinds 模块而 mix 位于 utils
模块。art crate 的模块结构相比使用它的开发者来说对编写它的开发者更有意义。其内部的 kinds 模块
和 utils 模块的组织结构并没有对尝试理解如何使用它的人提供任何有价值的信息。art crate 的模块结
构因不得不搞清楚所需的内容在何处和必须在 use 语句中指定模块名称而显得混乱和不便。
为了从公有 API 中去掉 crate 的内部组织，我们可以采用示例 14-3 中的 art crate 并增加 pub use 语句
来重导出项到顶层结构，如示例 14-5 所示：
文件名: src∕lib.rs
//! # Art
//!
//! A library for modeling artistic concepts.
pub use self::kinds::PrimaryColor;
pub use self::kinds::SecondaryColor;
pub use self::utils::mix;
pub mod kinds {
// --snip–

/// The primary colors according to the RYB color model.

pub enum PrimaryColor {

Red,

Yellow,

Blue,

}

/// The secondary colors according to the RYB color model.

pub enum SecondaryColor {

Orange,

Green,

Purple,

}

}
pub mod utils {
// --snip–

use crate::kinds:😗;

/// Combines two primary colors in equal amounts to create

/// a secondary color.

pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {

SecondaryColor::Orange

}

}
示例 14-5：增加 pub use 语句重导出项
现在此 crate 由 cargo doc 生成的 API 文档会在首页列出重导出的项以及其链接，如图 14-4 所示，这使
得 PrimaryColor 和 SecondaryColor 类型和 mix 函数更易于查找。
art 文档的首页，这里列出了重导出的项
art crate 的用户仍然可以看见和选择使用示例 14-4 中的内部结构，或者可以使用示例 14-5 中更为方便
的结构，如示例 14-6 所示：
文件名: src∕main.rs
use art::mix;
use art::PrimaryColor;
fn main() {
// --snip–

let red = PrimaryColor::Red;

let yellow = PrimaryColor::Yellow;

mix(red, yellow);

}
示例 14-6：一个使用 art crate 中重导出项的程序
对于有很多嵌套模块的情况，使用 pub use 将类型重导出到顶级结构对于使用 crate 的人来说将会是大
为不同的体验。
创建一个有用的公有 API 结构更像是一门艺术而非科学，你可以反复检视他们来找出最适合用户的 API。
pub use 提供了解耦组织 crate 内部结构和与终端用户体现的灵活性。观察一些你所安装的 crate 的代
码来看看其内部结构是否不同于公有 API。