改进rust代码的35种具体方法-类型(二十二)-最小化可见度

上一篇文章改进rust代码的35种具体方法-类型(二十一)-熟悉Cargo.toml版本使用

Rust允许将代码元素隐藏或暴露给代码库的其他部分。本项目探讨了为此提供的机制，并就应在何时何地使用它们提出建议。

可见性语法

Rust的基本可见性单位是模块。默认情况下，模块的项目（类型、方法、常量）是私有的，只能访问同一模块及其子模块中的代码。

需要更广泛可用的代码用pub关键字标记，使其向其他范围公开。对于大多数Rust语法功能，使功能pub不会自动公开内容——pub mod中的类型和功能不是公开的，也不是pub struct中的字段。然而，有几个例外情况是，将可见性应用于内容是有意义的：

公开枚举会自动使类型的变体也公开（以及这些变体中可能存在的任何字段）。
公开trait会自动公开该特征的方法。

因此，模块中的类型集合：

pub mod somemodule {
    // Making a `struct` public does not make its fields public.
    #[derive(Debug, Default)]
    pub struct AStruct {
        // By default fields are inaccessible.
        count: i32,
        // Fields have to be explicitly marked `pub` to be visible.
        pub name: String,
    }

    // Likewise, methods on the struct need individual `pub` markers.
    impl AStruct {
        // By default methods are inaccessible.
        fn canonical_name(&self) -> String {
            self.name.to_lowercase()
        }
        // Methods have to be explicitly marked `pub` to be visible.
        pub fn id(&self) -> String {
            format!("{}-{}", self.canonical_name(), self.count)
        }
    }

    // Making an `enum` public also makes all of its variants public.
    #[derive(Debug)]
    pub enum AnEnum {
        VariantOne,
        // Fields in variants are also made public.
        VariantTwo(u32),
        VariantThree { name: String, value: String },
    }

    // Making a `trait` public also makes all of its methods public.
    pub trait DoSomething {
        fn do_something(&self, arg: i32);
    }
}

允许访问pub的东西和前面提到的例外情况：

use somemodule::*;

let mut s = AStruct::default();
s.name = "Miles".to_string();
println!("s = {:?}, name='{}', id={}", s, s.name, s.id());

let e = AnEnum::VariantTwo(42);
println!("e = {e:?}");

#[derive(Default)]
pub struct DoesSomething;
impl DoSomething for DoesSomething {
    fn do_something(&self, _arg: i32) {}
}

let d = DoesSomething::default();
d.do_something(42);

但非pub的东西通常无法进入：

let mut s = AStruct::default();
s.name = "Miles".to_string();
println!("(inaccessible) s.count={}", s.count);
println!("(inaccessible) s.canonical_name()={}", s.canonical_name());

error[E0616]: field `count` of struct `somemodule::AStruct` is private
   --> src/main.rs:230:45
    |
230 |     println!("(inaccessible) s.count={}", s.count);
    |                                             ^^^^^ private field
error[E0624]: method `canonical_name` is private
   --> src/main.rs:231:56
    |
86  |         fn canonical_name(&self) -> String {
    |         ---------------------------------- private method defined here
...
231 |     println!("(inaccessible) s.canonical_name()={}", s.canonical_name());
    |                                         private method ^^^^^^^^^^^^^^
Some errors have detailed explanations: E0616, E0624.
For more information about an error, try `rustc --explain E0616`.

最常见的可见性标记是裸露的pub关键字，它使该项目对任何能够看到它所在的模块的东西可见。最后一个细节很重要：如果asomecratesomecrate::somemodule模块首先对其他代码不可见，那么它里面的任何pub仍然不可见。

然而，pub也有一些更具体的变体，允许限制可见性的范围。按有用性降序排列，如下所示：

pub(crate)：在拥有的 crate 中可以随时访问。这对于 crate 内部的整个函数特别有用，这些函数不应该暴露给外部 crate 的用户。
pub(super)：可以被当前模块的父模块及其子模块访问。这在具有深层模块结构的 crate 中，有时会有所帮助，可以有选择性地增加可见性。对于模块来说，这也是有效的可见性级别：一个简单的 mod mymodule 对其父模块或 crate 以及相应的子模块可见。
pub(in <path>)：可访问<path>中的代码，该代码必须是当前模块某些祖先模块的描述。这偶尔对组织源代码很有用，因为它允许将功能子集移动到公共API中不一定可见的子模块中。例如，Rust标准库将所有迭代器适配器整合到一个内部std::iter::adapters子模块中，并具有以下内容：
- 子模块中所有必需适配器方法的pub(in crate::iter)可见性标记，例如std::iter::adapters::map::Map::new。
- A pub use of all of the adapters:: types in the outer std::iter module.
pub(self)：相当于pub(in self)这相当于不是pub。这样做的用途非常模糊，例如减少代码生成宏所需的特殊情况数量。

如果您有一个对模块私有但未在该模块（及其子模块）中使用的代码项，Rust编译器将警告您：

pub mod anothermodule {
    // Private function that is not used within its module.
    fn inaccessible_fn(x: i32) -> i32 {
        x + 3
    }
}

虽然警告表示代码在其拥有的模块中“从未使用过”，但在实践中，此警告通常表明代码不能从模块外部使用，因为可见性限制不允许：

warning: function `inaccessible_fn` is never used
  --> src/main.rs:56:8
   |
56 |     fn inaccessible_fn(x: i32) -> i32 {
   |        ^^^^^^^^^^^^^^^
   |
   = note: `#[warn(dead_code)]` on by default