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 中实现数据封装的标准模式。