pub 可见性
什么是 pub
pub 是 Rust 的可见性修饰符,用来控制模块中的项能否被外部访问。Rust 的默认可见性是私有的——函数、结构体、枚举、常量、模块等如果不加 pub,就只能在定义它的模块内部使用。加了 pub 之后,项就可以被外部模块访问。
rust
mod account {
// 公开函数:外部可以调用
pub fn create(name: &str) -> String {
let id = generate_id(); // 内部可以调用私有函数
format!("账户 {} (ID: {})", name, id)
}
// 私有函数:只有模块内部能调用
fn generate_id() -> u32 {
42 // 简化示例
}
}
fn main() {
println!("{}", account::create("张三"));
// account::generate_id(); // 编译错误:私有函数
}可以标记为 pub 的项
几乎所有的项都可以标记为 pub:
rust
mod example {
// 公开常量
pub const VERSION: &str = "1.0.0";
// 公开静态变量
pub static COUNTER: std::sync::atomic::AtomicU32 =
std::sync::atomic::AtomicU32::new(0);
// 公开类型别名
pub type Result<T> = std::result::Result<T, String>;
// 公开枚举(枚举变体自动公开)
pub enum Color {
Red,
Green,
Blue,
Custom(u8, u8, u8),
}
// 公开结构体(但字段需要单独标记)
pub struct Config {
pub name: String, // 公开字段
pub debug: bool, // 公开字段
secret: String, // 私有字段
}
impl Config {
// 公开方法
pub fn new(name: &str) -> Self {
Config {
name: name.to_string(),
debug: false,
secret: String::from("hidden"),
}
}
// 私有方法
fn validate(&self) -> bool {
!self.name.is_empty()
}
// 公开方法可以调用私有方法
pub fn is_valid(&self) -> bool {
self.validate()
}
}
// 公开 trait
pub trait Printable {
fn print(&self);
}
// 公开函数
pub fn hello() {
println!("Hello from example module");
}
// 公开子模块
pub mod utils {
pub fn helper() {
println!("辅助函数");
}
}
}
fn main() {
println!("版本:{}", example::VERSION);
let config = example::Config::new("MyApp");
println!("名称:{}", config.name);
println!("有效:{}", config.is_valid());
// println!("{}", config.secret); // 编译错误:私有字段
let color = example::Color::Custom(255, 128, 0);
example::hello();
example::utils::helper();
}结构体字段的可见性
结构体本身标记为 pub 不意味着它的字段也是公开的。每个字段需要单独标记。
rust
mod user {
pub struct User {
pub name: String, // 公开:外部可读写
pub email: String, // 公开:外部可读写
password_hash: String, // 私有:外部不可访问
login_count: u32, // 私有:外部不可访问
}
impl User {
// 构造函数必须是公开的,因为外部不能直接设置私有字段
pub fn new(name: &str, email: &str, password: &str) -> Self {
User {
name: name.to_string(),
email: email.to_string(),
password_hash: format!("hash_{}", password), // 简化
login_count: 0,
}
}
// 通过公开方法提供对私有字段的受控访问
pub fn login_count(&self) -> u32 {
self.login_count
}
pub fn record_login(&mut self) {
self.login_count += 1;
}
pub fn verify_password(&self, password: &str) -> bool {
self.password_hash == format!("hash_{}", password)
}
}
}
fn main() {
let mut u = user::User::new("张三", "z@test.com", "123456");
// 可以访问公开字段
println!("名字:{}", u.name);
u.name = String::from("李四"); // 可以修改公开字段
// 不能访问私有字段
// println!("{}", u.password_hash); // 编译错误
// 通过公开方法间接访问
u.record_login();
println!("登录次数:{}", u.login_count());
println!("密码验证:{}", u.verify_password("123456"));
}枚举变体的可见性
和结构体不同,枚举只要本身是 pub 的,它的所有变体自动公开。
rust
mod status {
// 枚举是 pub 的,所有变体自动公开
pub enum HttpStatus {
Ok,
NotFound,
InternalError,
Custom(u16, String),
}
impl HttpStatus {
pub fn code(&self) -> u16 {
match self {
HttpStatus::Ok => 200,
HttpStatus::NotFound => 404,
HttpStatus::InternalError => 500,
HttpStatus::Custom(code, _) => *code,
}
}
pub fn message(&self) -> &str {
match self {
HttpStatus::Ok => "OK",
HttpStatus::NotFound => "Not Found",
HttpStatus::InternalError => "Internal Server Error",
HttpStatus::Custom(_, msg) => msg,
}
}
}
}
fn main() {
// 可以直接使用枚举变体
let s = status::HttpStatus::NotFound;
println!("{}: {}", s.code(), s.message());
let custom = status::HttpStatus::Custom(429, String::from("Too Many Requests"));
println!("{}: {}", custom.code(), custom.message());
}| 项类型 | pub 标记后 | 内部成员可见性 |
|---|---|---|
| 函数 | 外部可调用 | — |
| 结构体 | 外部可见类型名 | 字段需要单独标记 pub |
| 枚举 | 外部可见类型名 | 变体自动公开 |
| 常量/静态变量 | 外部可访问 | — |
| trait | 外部可见 | 方法自动公开 |
| 模块 | 外部可见 | 内部项需要单独标记 |
基本示例
封装一个简单的计数器模块:
rust
mod counter {
// 公开结构体,但内部状态是私有的
pub struct Counter {
value: i64, // 私有:不允许外部直接修改
step: i64, // 私有
pub name: String, // 公开:允许外部查看和修改名称
}
impl Counter {
pub fn new(name: &str) -> Self {
Counter {
value: 0,
step: 1,
name: name.to_string(),
}
}
pub fn with_step(name: &str, step: i64) -> Self {
Counter {
value: 0,
step,
name: name.to_string(),
}
}
// 公开方法:受控地修改状态
pub fn increment(&mut self) {
self.value += self.step;
}
pub fn decrement(&mut self) {
self.value -= self.step;
}
pub fn reset(&mut self) {
self.value = 0;
}
// 公开方法:只读访问私有字段
pub fn value(&self) -> i64 {
self.value
}
pub fn step(&self) -> i64 {
self.step
}
}
// 公开实现 Display
impl std::fmt::Display for Counter {
fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
write!(f, "{}={} (步长={})", self.name, self.value, self.step)
}
}
}
fn main() {
let mut c = counter::Counter::new("访问量");
c.increment();
c.increment();
c.increment();
println!("{}", c);
let mut c2 = counter::Counter::with_step("温度", 5);
c2.increment();
c2.increment();
println!("{}", c2);
c2.decrement();
println!("当前值:{}", c2.value());
}常见问题
问题一:pub 结构体为什么还需要给字段加 pub?
这是有意的设计。结构体可能有些字段需要公开(让外部读写),有些需要隐藏(保护内部状态)。如果 pub struct 自动公开所有字段,就无法实现封装了。
问题二:pub 的方法可以访问结构体的私有字段吗?
可以。impl 块中的所有方法(无论是否 pub)都可以访问结构体的所有字段,因为它们在同一个模块中。pub 只控制方法能否从外部调用。
问题三:trait 的方法需要加 pub 吗?
不需要。trait 中声明的方法默认就是公开的(作为接口的一部分)。给 trait 方法加 pub 会编译错误。
rust
trait MyTrait {
fn method(&self); // 正确:自动公开
// pub fn method(&self); // 编译错误
}问题四:如果不加 pub,谁能访问?
同一个模块内的代码可以访问,子模块也可以通过 super:: 访问父模块的私有项。外部模块(包括父模块访问子模块的私有项)不行。
适用场景
- API 设计:只公开必要的接口,隐藏实现细节
- 字段封装:用私有字段 + 公开方法实现受控访问
- 模块接口:通过
pub定义模块对外的公开 API - 库开发:控制哪些类型和函数对使用者可见
注意事项
- Rust 默认一切都是私有的,需要显式加
pub - 结构体的字段需要单独标记
pub - 枚举变体随枚举自动公开
- trait 方法不需要也不能加
pub pub只控制跨模块访问,同模块内的代码始终可以互相访问- 私有字段的结构体需要提供公开的构造函数
- 子模块可以访问父模块的私有项
总结
pub 是 Rust 的可见性修饰符,将默认私有的项标记为公开。它可以用在函数、结构体、枚举、常量、模块等几乎所有项上。结构体的字段需要单独标记 pub,枚举的变体则随枚举自动公开。pub 是封装的核心工具——通过只公开必要的接口、隐藏实现细节,让模块的使用者不需要(也不能)依赖内部实现。私有字段配合公开方法是 Rust 中实现数据封装的标准模式。