【Rust自学】14.3. 使用pub use导出方便使用的API

喜欢的话别忘了点赞、收藏加关注哦（加关注即可阅读全文），对接下来的教程有兴趣的可以关注专栏。谢谢喵！(=^･ω･=)

14.3.1. 使用pub use导出方便使用的API

在第七章中我们介绍了mod关键字，我们使用它来将代码组织为模块，其中介绍的pub关键字可以讲模块或是方法设置为公共的以便外部代码调用。而外部代码要将模块或是方法引入当前作用域就得使用use关键字。

使用这些关键字就可将代码组织为面向开发者友好的形式。但是这种结构对代码库的最终用户不一定特别友好。比如说crate的结构程序在开发时对于开发者很友好，但是对于使用者不够方便。开发者会把程序结构分为很多层，使用者想要找到这种深层结构中的某个类型就很费劲。比如说： my_crate::some_module::another_module::UsefulType，而比较好用的写法是my_crate::UsefulType。

对于这种问题，不需要开发者重新组织内部代码结构，使用pub use就可以重导出，创建一个于内部私有结构不同的对外公共结构。重导出这个操作会取得某个位置上的公共条目，并将其公开到另外一个位置，就好像它就定义在这个新的位置上。

看个例子：
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 {
        //...
    }
}

• kinds这个模块下有两个枚举类型，一个PrimaryColor一个SecondaryColor用于存储颜色变体。
• utils模块下有函数叫mix，这个函数的功能就是把PrimaryColor的变体两个颜色混合成为SecondaryColor颜色，这里没有放出其中的代码。
• 把枚举类型放在kinds下，把函数放在untils下对于开发者来说非常友好

main.rs:

use art::kinds::PrimaryColor;
use art::utils::mix;

fn main() {
    let red = PrimaryColor::Red;
    let yellow = PrimaryColor::Yellow;
    mix(red, yellow);
}

这里用到了lib.rs中的枚举类型和mix函数，为了引入作用域写了三层，而且枚举类型和函数在不同的模块中，对于使用者来说引入是非常麻烦。

此时生成的crate文档长这样：

如果我们使用重导入来重构代码呢：
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 {
    /// 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 {
        //...
    }
}

main.rs:

use art::mix; 
use art::PrimaryColor;

fn main() {
    let red = PrimaryColor::Red;
    let yellow = PrimaryColor::Yellow;
    mix(red, yellow);
}

这个时候调用枚举类型和函数就不需要一层层地写模块了。

此时生成的crate文档：

文档中出现了Re-exports部分，所有重新导入的条目都写在了这里，对于crate的实际使用者来说查找这些类型和函数就非常的方便了。