上一篇文章 改进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 theadapters::
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
可见性语义
与如何提高知名度的问题不同,是何时这样做的问题。对此普遍接受的答案尽可能少,至少对于任何将来可能被使用和重复使用的代码。
提出这个建议的第一个原因是,可见性的变更很难撤销。一旦一个 crate 项是公共的,就不能再将其设置为私有,否则会破坏使用 crate 的任何代码,从而需要进行主要版本的升级。相反,事实并非如此:将私人项目移动为公共项目通常只需要一个次要版本颠簸,并且不会让板条箱用户不受影响——阅读Rust的API兼容性指南,并注意只有当有pub
项目在起作用时,才会注意到有多少是相关的。
一个更重要但更微妙的偏爱隐私的理由是,它让你的选择保持开放。暴露的东西越多,未来需要固定的东西就越多(没有不兼容的变化)。如果您公开数据结构的内部实现细节,那么未来使用更高效算法的假定更改将成为突破性更改。如果您公开内部助手函数,一些外部代码将不可避免地取决于这些函数的确切细节。
当然,这只适用于可能具有多个用户且寿命较长的库代码。但没有什么比临时解决方案更永久的了,所以这是一个好习惯。
同样值得注意的是,这种限制可见性的建议绝不是这个项目或Rust所独有的: