pub(crate) 限制可见性
什么是 pub(crate)
pub(crate) 是一种受限的可见性修饰符,表示"在当前 crate 内部公开,但对外部 crate 不可见"。它比 pub(完全公开)更严格,比私有(不加修饰符)更宽松,是库开发中控制内部 API 的重要工具。
mod internal {
// pub(crate):crate 内任何地方都能访问,但外部 crate 看不到
pub(crate) fn helper() {
println!("crate 内部的辅助函数");
}
// pub:完全公开,外部 crate 也能访问
pub fn public_api() {
helper(); // 内部调用没问题
println!("公开的 API");
}
// 私有:只有当前模块和子模块能访问
fn secret() {
println!("完全私有");
}
}
fn main() {
internal::helper(); // 同一 crate 内可以调用
internal::public_api(); // 公开的,当然可以调用
// internal::secret(); // 编译错误:私有函数
}三种可见性的对比
| 修饰符 | 当前模块 | 当前 crate 其他模块 | 外部 crate |
|---|---|---|---|
| 无(私有) | 可访问 | 不可访问 | 不可访问 |
pub(crate) | 可访问 | 可访问 | 不可访问 |
pub | 可访问 | 可访问 | 可访问 |
mod visibility_demo {
// 私有:只有 visibility_demo 模块内部能用
fn private_fn() {
println!("私有");
}
// pub(crate):整个 crate 都能用
pub(crate) fn crate_fn() {
println!("crate 可见");
private_fn(); // 同模块内可以调用私有函数
}
// pub:谁都能用
pub fn public_fn() {
println!("完全公开");
crate_fn(); // 同 crate 内可以调用 pub(crate)
}
}
mod another_module {
pub fn test() {
// super::visibility_demo::private_fn(); // 编译错误:私有
super::visibility_demo::crate_fn(); // 可以:pub(crate)
super::visibility_demo::public_fn(); // 可以:pub
}
}
fn main() {
another_module::test();
}pub(crate) 用在不同项上
mod data {
// pub(crate) 结构体
pub(crate) struct InternalConfig {
pub(crate) db_url: String,
pub(crate) max_connections: u32,
secret_key: String, // 仍然可以有私有字段
}
impl InternalConfig {
pub(crate) fn new(db_url: &str, max_conn: u32) -> Self {
InternalConfig {
db_url: db_url.to_string(),
max_connections: max_conn,
secret_key: String::from("internal-key"),
}
}
// pub(crate) 方法
pub(crate) fn connection_info(&self) -> String {
format!("{} (最大连接数: {})", self.db_url, self.max_connections)
}
}
// pub(crate) 常量
pub(crate) const INTERNAL_VERSION: &str = "0.1.0-internal";
// pub(crate) 类型别名
pub(crate) type DbResult<T> = Result<T, String>;
// pub(crate) 枚举
pub(crate) enum CacheStrategy {
None,
Memory,
Disk,
}
}
mod service {
use super::data::{InternalConfig, INTERNAL_VERSION, CacheStrategy};
pub fn start() {
let config = InternalConfig::new("postgres://localhost/db", 10);
println!("内部版本:{}", INTERNAL_VERSION);
println!("数据库:{}", config.connection_info());
let strategy = CacheStrategy::Memory;
match strategy {
CacheStrategy::None => println!("无缓存"),
CacheStrategy::Memory => println!("内存缓存"),
CacheStrategy::Disk => println!("磁盘缓存"),
}
}
}
fn main() {
service::start();
}库开发中的实际用途
pub(crate) 在库(library crate)开发中特别有用。库通常有很多内部辅助函数和类型,这些需要在库的多个模块之间共享,但不应该暴露给库的使用者。
// 假设这是一个库 crate(lib.rs)的内容
mod parser {
// 内部辅助结构体:库的其他模块需要用,但使用者不需要知道
pub(crate) struct Token {
pub(crate) kind: TokenKind,
pub(crate) value: String,
}
pub(crate) enum TokenKind {
Number,
Operator,
Identifier,
}
pub(crate) fn tokenize(input: &str) -> Vec<Token> {
// 简化的分词逻辑
let mut tokens = Vec::new();
for word in input.split_whitespace() {
let kind = if word.parse::<f64>().is_ok() {
TokenKind::Number
} else if ["+", "-", "*", "/"].contains(&word) {
TokenKind::Operator
} else {
TokenKind::Identifier
};
tokens.push(Token {
kind,
value: word.to_string(),
});
}
tokens
}
}
mod evaluator {
use super::parser::{Token, TokenKind, tokenize};
// pub(crate) 的内部求值函数
pub(crate) fn evaluate_tokens(tokens: &[Token]) -> String {
let descriptions: Vec<String> = tokens.iter().map(|t| {
let kind_str = match t.kind {
TokenKind::Number => "数字",
TokenKind::Operator => "运算符",
TokenKind::Identifier => "标识符",
};
format!("{}({})", kind_str, t.value)
}).collect();
descriptions.join(", ")
}
}
// 公开的 API——这才是使用者看到的
pub fn analyze(input: &str) -> String {
let tokens = parser::tokenize(input);
evaluator::evaluate_tokens(&tokens)
}
fn main() {
// 使用者只需要调用 analyze
let result = analyze("x + 3 * y");
println!("分析结果:{}", result);
}基本示例
用 pub(crate) 组织一个内部共享的日志系统:
mod logger {
use std::sync::atomic::{AtomicU32, Ordering};
// crate 内部共享的日志级别
pub(crate) static LOG_COUNT: AtomicU32 = AtomicU32::new(0);
#[derive(Clone, Copy, PartialEq, PartialOrd)]
pub(crate) enum Level {
Debug,
Info,
Warn,
Error,
}
impl Level {
pub(crate) fn label(&self) -> &'static str {
match self {
Level::Debug => "DEBUG",
Level::Info => "INFO",
Level::Warn => "WARN",
Level::Error => "ERROR",
}
}
}
// crate 内部使用的日志函数
pub(crate) fn log(level: Level, module: &str, message: &str) {
let count = LOG_COUNT.fetch_add(1, Ordering::Relaxed) + 1;
println!("[{:04}][{}] {}: {}", count, level.label(), module, message);
}
}
mod database {
use super::logger;
pub fn connect(url: &str) {
logger::log(logger::Level::Info, "database", &format!("连接到 {}", url));
// 模拟连接
logger::log(logger::Level::Debug, "database", "连接成功");
}
}
mod api {
use super::logger;
pub fn handle_request(path: &str) {
logger::log(logger::Level::Info, "api", &format!("处理请求: {}", path));
if path == "/error" {
logger::log(logger::Level::Error, "api", "请求处理失败");
} else {
logger::log(logger::Level::Debug, "api", "请求处理完成");
}
}
}
fn main() {
database::connect("postgres://localhost/mydb");
api::handle_request("/users");
api::handle_request("/error");
println!("\n总日志条数:{}",
logger::LOG_COUNT.load(std::sync::atomic::Ordering::Relaxed));
}常见问题
问题一:pub(crate) 和 pub 在二进制 crate 中有区别吗?
二进制 crate(有 main 函数的程序)没有外部使用者,所以 pub(crate) 和 pub 在功能上没有区别。但使用 pub(crate) 可以表达"这个项是内部 API"的意图,对代码维护有帮助。如果将来代码被重构为库,pub(crate) 也能自动限制可见性。
问题二:pub(crate) 的项在文档中会出现吗?
cargo doc 默认不会为 pub(crate) 的项生成文档,因为它们不属于公开 API。用 cargo doc --document-private-items 可以包含它们。
问题三:结构体是 pub(crate) 但字段是 pub 会怎样?
字段的实际可见范围受到结构体可见性的限制。如果结构体是 pub(crate),即使字段标记为 pub,外部 crate 也看不到这个结构体,自然也访问不到字段。
问题四:什么时候用 pub(crate) 而不是 pub?
在库开发中,如果一个项需要在 crate 内部多个模块之间共享,但不应该成为公开 API 的一部分,就用 pub(crate)。这样可以在不破坏外部兼容性的前提下自由修改内部实现。
适用场景
- 库的内部 API:crate 内部多个模块共享,但不暴露给使用者
- 内部辅助工具:日志、错误处理等内部基础设施
- 内部数据类型:只在 crate 内部传递的结构体和枚举
- 意图声明:即使在二进制 crate 中,也能表达"这是内部 API"
注意事项
pub(crate)的项在整个 crate 内可见,对外部 crate 不可见- 在二进制 crate 中
pub(crate)和pub功能等价,但语义不同 pub(crate)的项不会出现在cargo doc生成的文档中- 字段的可见范围受结构体可见性的限制
pub(crate)让你可以自由重构内部实现而不影响外部使用者
总结
pub(crate) 提供了介于私有和完全公开之间的可见性——在当前 crate 内公开,对外部 crate 隐藏。它在库开发中特别有用,让内部模块可以共享辅助函数和类型,同时保持公开 API 的整洁。即使在二进制 crate 中,pub(crate) 也能清晰地表达"这是内部 API"的意图。使用 pub(crate) 标记内部项,可以在不影响外部兼容性的前提下自由修改实现细节。