pub(super) 父级可见性
什么是 pub(super)
pub(super) 是 Rust 中最精细的可见性修饰符之一,表示"只对父模块可见"。用 pub(super) 标记的项可以被当前模块和父模块访问,但对父模块之外的其他模块不可见。它适合那些"子模块之间需要共享,但不应该暴露到更外层"的场景。
mod parent {
mod child_a {
// pub(super) 让父模块 parent 能访问
pub(super) fn internal_helper() {
println!("child_a 的内部辅助函数");
}
}
mod child_b {
// child_b 不能直接访问 child_a 的 pub(super) 项
// 但父模块 parent 可以
}
pub fn run() {
// 父模块可以访问 pub(super) 的项
child_a::internal_helper();
}
}
fn main() {
parent::run();
// parent::child_a::internal_helper(); // 编译错误:child_a 是私有模块
}pub(super) 的可见范围
| 修饰符 | 当前模块 | 父模块 | 祖父模块 | crate 其他模块 | 外部 crate |
|---|---|---|---|---|---|
| 无(私有) | 可 | 不可 | 不可 | 不可 | 不可 |
pub(super) | 可 | 可 | 不可 | 不可 | 不可 |
pub(crate) | 可 | 可 | 可 | 可 | 不可 |
pub | 可 | 可 | 可 | 可 | 可 |
mod grandparent {
pub mod parent {
pub mod child {
// 只有 parent 和 child 能访问
pub(super) fn for_parent() {
println!("只给父模块用");
}
// 整个 crate 都能访问
pub(crate) fn for_crate() {
println!("crate 内部都能用");
}
// 完全公开
pub fn for_everyone() {
println!("谁都能用");
}
}
pub fn test_parent() {
child::for_parent(); // 可以:父模块
child::for_crate(); // 可以:同 crate
child::for_everyone(); // 可以:公开的
}
}
pub fn test_grandparent() {
// parent::child::for_parent(); // 编译错误:超出 pub(super) 范围
parent::child::for_crate(); // 可以:同 crate
parent::child::for_everyone(); // 可以:公开的
}
}
fn main() {
grandparent::parent::test_parent();
grandparent::test_grandparent();
}实际应用:子模块之间的协作
pub(super) 常用于让多个子模块通过父模块来协作,而不将实现细节暴露到更外层。
mod http_handler {
// 请求解析子模块
mod parser {
pub(super) struct ParsedRequest {
pub(super) method: String,
pub(super) path: String,
pub(super) body: Option<String>,
}
pub(super) fn parse(raw: &str) -> ParsedRequest {
// 简化的解析逻辑
let parts: Vec<&str> = raw.splitn(3, ' ').collect();
ParsedRequest {
method: parts.get(0).unwrap_or(&"GET").to_string(),
path: parts.get(1).unwrap_or(&"/").to_string(),
body: parts.get(2).map(|s| s.to_string()),
}
}
}
// 响应构建子模块
mod response {
pub(super) struct HttpResponse {
pub(super) status: u16,
pub(super) body: String,
}
pub(super) fn ok(body: &str) -> HttpResponse {
HttpResponse {
status: 200,
body: body.to_string(),
}
}
pub(super) fn not_found() -> HttpResponse {
HttpResponse {
status: 404,
body: String::from("Not Found"),
}
}
}
// 父模块整合子模块的功能,提供公开 API
pub fn handle(raw_request: &str) -> String {
let req = parser::parse(raw_request);
let resp = match req.path.as_str() {
"/" => response::ok("首页"),
"/about" => response::ok("关于页"),
_ => response::not_found(),
};
format!("[{}] {} {} -> {}", resp.status, req.method, req.path, resp.body)
}
}
fn main() {
println!("{}", http_handler::handle("GET / body"));
println!("{}", http_handler::handle("POST /about data"));
println!("{}", http_handler::handle("GET /unknown"));
// 外部不能直接访问 parser 或 response 子模块
// http_handler::parser::parse("..."); // 编译错误
}pub(super) 用在结构体字段上
mod database {
mod connection {
pub(super) struct Connection {
pub(super) host: String,
pub(super) port: u16,
connected: bool, // 仍然可以有私有字段
}
impl Connection {
pub(super) fn new(host: &str, port: u16) -> Self {
Connection {
host: host.to_string(),
port,
connected: false,
}
}
pub(super) fn connect(&mut self) {
self.connected = true;
println!("已连接到 {}:{}", self.host, self.port);
}
pub(super) fn is_connected(&self) -> bool {
self.connected
}
}
}
// 父模块可以使用 pub(super) 的结构体
pub fn start() {
let mut conn = connection::Connection::new("localhost", 5432);
println!("主机:{},端口:{}", conn.host, conn.port);
conn.connect();
println!("已连接:{}", conn.is_connected());
}
}
fn main() {
database::start();
// database::connection::Connection::new("...", 0); // 编译错误
}基本示例
用 pub(super) 实现一个内部分层的验证模块:
mod validator {
// 规则子模块:定义各种验证规则
mod rules {
pub(super) fn is_non_empty(s: &str) -> Result<(), String> {
if s.trim().is_empty() {
Err(String::from("不能为空"))
} else {
Ok(())
}
}
pub(super) fn is_valid_email(s: &str) -> Result<(), String> {
if s.contains('@') && s.contains('.') {
Ok(())
} else {
Err(format!("'{}' 不是有效的邮箱格式", s))
}
}
pub(super) fn is_min_length(s: &str, min: usize) -> Result<(), String> {
if s.len() >= min {
Ok(())
} else {
Err(format!("长度至少 {} 个字符,当前 {}", min, s.len()))
}
}
pub(super) fn is_in_range(n: i32, min: i32, max: i32) -> Result<(), String> {
if n >= min && n <= max {
Ok(())
} else {
Err(format!("{} 不在 {}-{} 范围内", n, min, max))
}
}
}
// 消息子模块:格式化错误消息
mod messages {
pub(super) fn format_error(field: &str, error: &str) -> String {
format!("字段 '{}' 验证失败:{}", field, error)
}
pub(super) fn format_success(field: &str) -> String {
format!("字段 '{}' 验证通过", field)
}
}
// 公开的验证 API
pub fn validate_username(name: &str) -> Result<(), String> {
rules::is_non_empty(name)
.map_err(|e| messages::format_error("用户名", &e))?;
rules::is_min_length(name, 3)
.map_err(|e| messages::format_error("用户名", &e))?;
println!("{}", messages::format_success("用户名"));
Ok(())
}
pub fn validate_email(email: &str) -> Result<(), String> {
rules::is_non_empty(email)
.map_err(|e| messages::format_error("邮箱", &e))?;
rules::is_valid_email(email)
.map_err(|e| messages::format_error("邮箱", &e))?;
println!("{}", messages::format_success("邮箱"));
Ok(())
}
pub fn validate_age(age: i32) -> Result<(), String> {
rules::is_in_range(age, 0, 150)
.map_err(|e| messages::format_error("年龄", &e))?;
println!("{}", messages::format_success("年龄"));
Ok(())
}
}
fn main() {
let tests = vec![
("用户名", validator::validate_username("张三") ),
("用户名", validator::validate_username("ab") ),
("邮箱", validator::validate_email("test@mail.com") ),
("邮箱", validator::validate_email("invalid") ),
("年龄", validator::validate_age(25) ),
("年龄", validator::validate_age(200) ),
];
println!("\n--- 错误汇总 ---");
for (label, result) in &tests {
if let Err(e) = result {
println!("{}: {}", label, e);
}
}
}常见问题
问题一:pub(super) 和直接把项定义在父模块中有什么区别?
功能上类似,但代码组织不同。pub(super) 让你把代码分散到子模块中组织,同时限制可见性。直接定义在父模块中会让父模块文件变得庞大。
问题二:pub(super) 的项能被兄弟模块访问吗?
不能直接访问。pub(super) 只对父模块可见。兄弟模块要用的话,需要父模块做一个中转(调用后传递结果),或者改用 pub(crate)。
问题三:pub(in path) 是什么?
pub(in path) 是更灵活的可见性语法,可以指定任意祖先模块。比如 pub(in crate::a::b) 表示只对 crate::a::b 模块可见。pub(super) 其实是 pub(in super) 的简写。
mod a {
pub mod b {
pub mod c {
// 只对 a::b 可见
pub(in crate::a::b) fn restricted() {
println!("只对 a::b 可见");
}
}
pub fn call() {
c::restricted(); // 可以
}
}
}
fn main() {
a::b::call();
}问题四:什么时候该用 pub(super)?
当子模块的某些内部实现需要被父模块使用,但不应该暴露到更外层时。典型场景是"父模块整合子模块的功能并提供统一的公开 API"。
适用场景
- 内部分层:子模块提供
pub(super)的功能,父模块整合后提供pub的 API - 实现隐藏:把解析、验证、格式化等内部逻辑拆到子模块中
- 受控共享:比私有更宽松(父模块能用),比
pub(crate)更严格(只有父模块能用)
注意事项
pub(super)只对直接父模块可见,不包括祖父模块- 兄弟模块不能直接访问
pub(super)的项 pub(super)是pub(in super)的简写- 结构体字段也可以用
pub(super) - 使用场景相对较少,大多数情况下
pub和pub(crate)就够了 pub(in path)可以指定更精确的可见性范围
总结
pub(super) 将项的可见性限制为"只对父模块可见"。它比私有更宽松(父模块可以访问),比 pub(crate) 更严格(只有父模块可以访问)。最典型的用法是子模块把内部实现标记为 pub(super),父模块整合这些实现后对外提供统一的 pub 接口。这种模式让代码既有良好的模块化组织,又能精确控制每一层的可见性。pub(super) 是 pub(in super) 的简写,Rust 还提供了 pub(in path) 语法来指定任意祖先模块的可见性。