You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

15 KiB

使用use及受限可见性

如果代码中,通篇都是crate::front_of_house::hosting::add_to_waitlist这样的函数调用形式,我不知道有谁会喜欢,也许靠代码行数赚工资的人会很喜欢,反正强迫症肯定受不了,而且悲伤的是程序员大多都有强迫症。。。

因此我们需要一个办法来简化这种使用方式在Rust中可以使用use关键字把路径提前引入到当前作用域中,随后的调用就可以省略该路径,极大的简化了代码。

基本引入方式

在Rust中引入模块中的项有两种方式绝对路径和相对路径,这两者在前面章节都有讲过,就不再赘述,先来看看使用绝对路径的引入方式。

绝对路径引入模块

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
}

这里,我们使用use和绝对路径的方式,将hosting模块引入到当前作用域中,然后只需通过hosting::add_to_waitlist的方式,即可调用目标模块中的函数,相比crate::front_of_house::hosting::add_to_waitlist()的方式要简单的多,那么还能更简单吗?

相对路径引入模块中的函数

在下面代码中,我们不仅要使用相对路径进行引入,而且与上面引入hosting模块不同,直接引入该模块中的add_to_waitlist函数:

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use front_of_house::hosting::add_to_waitlist;

pub fn eat_at_restaurant() {
    add_to_waitlist();
    add_to_waitlist();
    add_to_waitlist();
}

很明显,三兄弟又变得更短了,不过,怎么觉得这句话怪怪的。。

引入模块还是函数

从使用简洁性来说,引入函数自然是更甚一筹,但是在某些时候,引入模块会更好:

  • 需要引入同一个模块的多个函数
  • 作用域中存在同名函数

在以上两种情况中, 使用use front_of_house::hosting引入模块要比use front_of_house::hosting::add_to_waitlist;引入函数更好。

例如,如果想使用HashMap,那么直接引入该结构体是比引入模块更好的选择,因为在collections模块中,我们只需要使用一个HashMap结构体:

use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}

其实严格来说,对于引用方式并没有需要遵守的惯例,主要还是取决于你的喜好,不过我们建议:优先使用最细粒度(引入函数、结构体等)的引用方式,如果引起了某种麻烦(例如前面两种情况),再使用引入模块的方式

避免同名引用

根据上一章节的内容,我们只要保证同一个模块中不存在同名项就行,模块之间、包之间的同名,谁管的着谁啊,话虽如此,一起看看,如果遇到同名的情况该如何处理.

模块::函数

use std::fmt;
use std::io;

fn function1() -> fmt::Result {
    // --snip--
}

fn function2() -> io::Result<()> {
    // --snip--
}

上面的例子给出了很好的解决方案,使用模块引入的方式,具体的Result通过模块::Result的方式进行调用。

可以看出,避免同名冲突的关键,就是使用父模块的方式来调用,除此之外,还可以给予引入的项一个新的名称。

as别名引用

对于同名冲突问题,还可以使用as关键字来解决。它可以赋予引入项一个全新的名称:

use std::fmt::Result;
use std::io::Result as IoResult;

fn function1() -> Result {
    // --snip--
}

fn function2() -> IoResult<()> {
    // --snip--
}

如上所示,首先通过use std::io::ResultResult引入到作用域,然后使用as给予它一个全新的名称IoResult,这样就不会再产生冲突:

  • Result代表std::fmt::Result
  • IoResult代表std:io::Result

引入项再导出

当外部的模块项A被引入到当前模块中时,它的可见性自动被设置为私有的,如果你允许其它外部代码引入我们模块中的A,那么可以对它进行再导出:

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
}

如上,使用pub use即可实现。这里use代表引入hosting模块到当前作用域,pub表示将该引入的内容再度设置为可见。

当你希望将内部的实现细节隐藏起来或者按照某个目的组织代码时,可以使用pub use再导出例如统一使用一个模块来提供对外的API那该模块就可以引入其它模块中的API然后进行再导出最终对于用户来说所有的API都是由一个模块统一提供的。

使用三方包

之前我们一直在引入标准库模块或者自定义模块,现在来引入下三方包中的模块,关于如何引入外部依赖,我们在Cargo入门中就有讲,这里直接给出操作步骤:

  1. 修改Cargo.toml文件[dependencies]区域添加一行: rand = "0.8.3"
  2. 此时,如果你用的是VSCoderust-analyzer插件,该插件会自动拉取该库,你可能需要等它完成后,再进行下一步(VSCODE左下角有提示)

好了,此时,rand包已经被我们添加到依赖中,下一步就是在代码中使用:

use rand::Rng;

fn main() {
    let secret_number = rand::thread_rng().gen_range(1..101);
}

这里使用use引入了三方包rand中的Rng特征,因为我们需要调用的gen_range方法定义在该特征中。

crates.io, lib.rs

Rust社区已经为我们贡献了大量高质量的三方包你可以在crates.io或者lib.rs中检索和使用,从目前来说查找包更推荐lib.rs,搜索功能更强大,内容展示也更加合理, 但是下载依赖包还是得用crates.io

你可以在网站上搜索rand包,看看它的文档使用方式是否和我们之前引入方式相一致: 在网上找到想要的包,然后将你想要的包和版本信息写入到Cargo.toml中。

使用{}简化引入方式

对于以下一行一行的引入方式:

use std::collections::HashMap;
use std::collections::BTreeMap;
use std::collections::HashSet;

use std::cmp::Ordering;
use std::io;

可以使用{}来一起引入进来,在大型项目中,使用这种方式来引入,可以减少大量use的使用:

use std::collections::{HashMap,BTreeMap,HashSet};
use std::{cmp::Ordering, io};

对于下面的同时引入模块和模块中的项:

use std::io;
use std::io::Write;

可以使用{}的方式进行简化:

use std::io::{self, Write};

self

上面使用到了模块章节提到的self关键字,用来替代模块自身,结合上一节中的self,可以得出它在模块中的两个用途:

  • use self::xxx,表示加载当前模块中的xxx。此时self可省略
  • use xxx::{self, yyy},表示,加载当前路径下模块xxx本身,以及模块xxx下的yyy

使用*引入模块下的所有项

对于之前一行一行引入std::collections的方式,我们还可以使用

use std::collections::*;

以上这种方式来引入std::collections模块下的所有公共项,这些公共项自然包含了HashMapHashSet等想手动引入的集合类型。

当使用*来引入的时候要格外小心,因为你很难知道到底哪些被引入到了当前作用域中,有哪些会和你自己程序中的名称相冲突:

use std::collections::*;

struct HashMap;
fn main() {
   let mut v =  HashMap::new();
   v.insert("a", 1);
}

以上代码中,std::collection::HashMap*引入到当前作用域,但是由于存在另一个同名的结构体,因此HashMap::new根本不存在,因为对于编译器来说,本地同名类型的优先级更高。

在实际项目中,这种引用方式往往用于快速写测试代码,它可以把所有东西一次性引入到tests模块中。

受限的可见性

在上一节中,我们学习了可见性这个概念这也是模块体系中最为核心的概念控制了模块中哪些内容可以被外部看见但是在实际使用时光被外面看到还不行我们还想控制哪些人能看这就是Rust提供的受限可见性。

例如在Rust中包是一个模块树我们可以通过pub(crate) item;这种方式来实现:item虽然是对外可见的,但是只在当前包内可见,外部包无法引用到该item

如果我们想要让某一项可以在整个包中都可以被使用,那么有两种办法:

  • 在包根中定义一个非pub类型的X(父模块的项对子模块都是可见的,因此包根中的项对模块树上的所有模块都可见)
  • 在子模块中定义一个pub类型的Y,同时通过use将其引入到包根
mod a {
    pub mod b {
        pub fn c() {
            println!("{:?}",crate::X);
        }

        #[derive(Debug)]
        pub struct Y;
    }
}

#[derive(Debug)]
struct X;
use a::b::Y;
fn d() {
    println!("{:?}",Y);
}

以上代码充分说明了之前两种办法的使用方式,但是有时我们会遇到这两种方法都不太好用的时候。例如希望对于某些特定的模块可见,但是对于其他模块又不可见:

// 目标: `a` 导出 `I`, `bar`, and `foo`, 其他的不导出
pub mod a {
    pub const I: i32 = 3;

    fn semisecret(x: i32) -> i32  { use self::b::c::J; x + J }

    pub fn bar(z: i32) -> i32 { semisecret(I) * z }
    pub fn foo(y: i32) -> i32 { semisecret(I) + y }

    mod b {
        mod c {
            const J: i32 = 4;
        }
    }
}

这段代码会报错,因为与父模块中的项对子模块可见相反,子模块中的项对父模块是不可见的。这里a->b->c形成了父子模块链,那c中的J自然对a模块不可见。

如果使用之前的可见性方式,那么要保持J私有,同时让a继续使用semisecret函数的办法是将该函数移动到c模块中,然后用pub use进行再导出:

pub mod a {
    pub const I: i32 = 3;

    use self::b::semisecret;

    pub fn bar(z: i32) -> i32 { semisecret(I) * z }
    pub fn foo(y: i32) -> i32 { semisecret(I) + y }

    mod b {
        pub use self::c::semisecret;
        mod c {
            const J: i32 = 4; 
            pub fn semisecret(x: i32) -> i32  { x + J }
        }
    }
}

这段代码说实话问题不大,但是有些破坏了我们之前的逻辑,如果想保持代码逻辑,同时又只让Ja内可见怎么办?

pub mod a {
    pub const I: i32 = 3;

    fn semisecret(x: i32) -> i32  { use self::b::c::J; x + J }

    pub fn bar(z: i32) -> i32 { semisecret(I) * z }
    pub fn foo(y: i32) -> i32 { semisecret(I) + y }

    mod b {
        pub(in crate::a) mod c {
            pub(in crate::a) const J: i32 = 4;
        }
    }
}

通过pub(in crate::a)的方式,我们指定了模块c和常量J的可见范围都是a模块中,a之外的模块是完全访问不到它们的。

限制可见性语法

pub(crate)pub(in crate::a)就是限制可见性语法, 前者是限制在整个包内可见,后者是通过绝对路径,限制在包内的某个模块内可见,总结一下:

  • pub意味着可见性无任何限制
  • pub(crate), 表示在当前包可见
  • pub(self), 在当前模块可见
  • pub(super),在父模块可见
  • pub(in <path>), 表示在某个路径代表的模块中可见, path必须是父模块或者祖先模块

一个综合例子

// 一个名为 `my_mod` 的模块
mod my_mod {
    // 模块中的项默认具有私有的可见性
    fn private_function() {
        println!("called `my_mod::private_function()`");
    }

    // 使用 `pub` 修饰语来改变默认可见性。
    pub fn function() {
        println!("called `my_mod::function()`");
    }

    // 在同一模块中,项可以访问其它项,即使它是私有的。
    pub fn indirect_access() {
        print!("called `my_mod::indirect_access()`, that\n> ");
        private_function();
    }

    // 模块也可以嵌套
    pub mod nested {
        pub fn function() {
            println!("called `my_mod::nested::function()`");
        }

        #[allow(dead_code)]
        fn private_function() {
            println!("called `my_mod::nested::private_function()`");
        }

        // 使用 `pub(in path)` 语法定义的函数只在给定的路径中可见。
        // `path` 必须是父模块parent module或祖先模块ancestor module
        pub(in crate::my_mod) fn public_function_in_my_mod() {
            print!("called `my_mod::nested::public_function_in_my_mod()`, that\n > ");
            public_function_in_nested()
        }

        // 使用 `pub(self)` 语法定义的函数则只在当前模块中可见。
        pub(self) fn public_function_in_nested() {
            println!("called `my_mod::nested::public_function_in_nested");
        }

        // 使用 `pub(super)` 语法定义的函数只在父模块中可见。
        pub(super) fn public_function_in_super_mod() {
            println!("called my_mod::nested::public_function_in_super_mod");
        }
    }

    pub fn call_public_function_in_my_mod() {
        print!("called `my_mod::call_public_funcion_in_my_mod()`, that\n> ");
        nested::public_function_in_my_mod();
        print!("> ");
        nested::public_function_in_super_mod();
    }

    // `pub(crate)` 使得函数只在当前包中可见
    pub(crate) fn public_function_in_crate() {
        println!("called `my_mod::public_function_in_crate()");
    }

    // 嵌套模块的可见性遵循相同的规则
    mod private_nested {
        #[allow(dead_code)]
        pub fn function() {
            println!("called `my_mod::private_nested::function()`");
        }
    }
}

fn function() {
    println!("called `function()`");
}

fn main() {
    // 模块机制消除了相同名字的项之间的歧义。
    function();
    my_mod::function();

    // 公有项,包括嵌套模块内的,都可以在父模块外部访问。
    my_mod::indirect_access();
    my_mod::nested::function();
    my_mod::call_public_function_in_my_mod();

    // pub(crate) 项可以在同一个 crate 中的任何地方访问
    my_mod::public_function_in_crate();

    // pub(in path) 项只能在指定的模块中访问
    // 报错!函数 `public_function_in_my_mod` 是私有的
    //my_mod::nested::public_function_in_my_mod();
    // 试一试 ^ 取消该行的注释

    // 模块的私有项不能直接访问,即便它是嵌套在公有模块内部的

    // 报错!`private_function` 是私有的
    //my_mod::private_function();
    // 试一试 ^ 取消此行注释

    // 报错!`private_function` 是私有的
    //my_mod::nested::private_function();
    // 试一试 ^ 取消此行的注释

    // Error! `private_nested` is a private module
    //my_mod::private_nested::function();
    // 试一试 ^ 取消此行的注释
}