pub(super) 父级可见性 ​

什么是 pub(super) ​

pub(super) 是 Rust 中最精细的可见性修饰符之一,表示"只对父模块可见"。用 pub(super) 标记的项可以被当前模块和父模块访问,但对父模块之外的其他模块不可见。它适合那些"子模块之间需要共享,但不应该暴露到更外层"的场景。

rust
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可可可可可
rust
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) 常用于让多个子模块通过父模块来协作,而不将实现细节暴露到更外层。

rust
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) 用在结构体字段上 ​

rust
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) 实现一个内部分层的验证模块:

rust
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) 的简写。

rust
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) 语法来指定任意祖先模块的可见性。