Rust / 系统课时
控制可见性
控制可见性
Rust 的可见性决定“某个名字能从哪里被访问”。这一节用一个可运行示例串起私有默认、pub、pub(crate)、pub(super) 与 pub(in path),并说明公开类型的字段为何仍可能保持私有,帮助你把模块边界收紧到真正需要的范围。
学习目标
- 判断模块、函数、类型和字段的默认可见范围
- 使用
pub与受限可见性表达不同层级的访问权限 - 识别“类型公开但字段不公开”等常见边界
默认规则与 pub
模块中的项默认是私有的,只能在隐私规则允许的模块范围内访问。加上 pub 后,项可以从其所有祖先允许到达的路径访问;因此“某个函数是 pub”并不代表外部一定能调用它,它所在的父模块也必须形成可达的公开路径。
结构体尤其容易误判:pub struct 只公开类型名,字段仍默认私有。要允许调用者直接读取或修改字段,字段本身也要显式标记 pub 或受限可见性。
用受限可见性收紧范围
pub(crate) 表示整个当前 Crate 可见;pub(super) 把访问范围限制在父模块;pub(in crate::app) 则把范围限制在指定祖先模块。受限形式适合内部协作接口:既避免把实现细节暴露成公共 API,又比完全私有更便于模块之间复用。

下面的单文件程序展示几种权限同时存在时的行为:
mod app {
pub mod api {
pub struct User {
pub name: String,
pub(crate) id: u64,
secret: String,
}
impl User {
pub fn new(name: &str, id: u64, secret: &str) -> Self {
Self {
name: name.to_string(),
id,
secret: secret.to_string(),
}
}
pub fn masked_secret(&self) -> String {
let first = self.secret.chars().next().unwrap_or('*');
format!("{first}***")
}
}
}
mod service {
pub(super) fn label(id: u64) -> String {
format!("user-{id}")
}
pub(in crate::app) fn audit() -> &'static str {
"audit-ok"
}
}
pub fn run() {
let user = api::User::new("Ada", 7, "rust");
println!("{} {} {}", user.name, user.id, user.masked_secret());
println!("{} {}", service::label(user.id), service::audit());
}
}
fn main() {
app::run();
}预期输出:
Ada 7 r***
user-7 audit-oksecret 没有任何 pub 修饰,因此 app::run 不能直接读取,只能通过 api 模块公开的方法间接访问。id 使用 pub(crate),所以同一 Crate 内的 app 可以读取,但其他 Crate 不行。
选择最小必要范围
设计可见性时,可以从“最窄权限”开始:只在当前模块使用就保持私有;父模块需要调用时考虑 pub(super);整个 Crate 内共享时用 pub(crate);只有真正属于外部稳定接口的项才使用无限制 pub。
还要注意,公开函数签名中出现的类型也必须对调用方可见,否则会形成无法正常使用的接口。把可见性当作模块设计的一部分,而不是编译报错后再临时补 pub,通常能得到更清晰的边界。