pub(crate) 限制可见性 ​

什么是 pub(crate) ​

pub(crate) 是一种受限的可见性修饰符,表示"在当前 crate 内部公开,但对外部 crate 不可见"。它比 pub(完全公开)更严格,比私有(不加修饰符)更宽松,是库开发中控制内部 API 的重要工具。

rust
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可访问可访问可访问
rust
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) 用在不同项上 ​

rust
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)开发中特别有用。库通常有很多内部辅助函数和类型,这些需要在库的多个模块之间共享,但不应该暴露给库的使用者。

rust
// 假设这是一个库 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) 组织一个内部共享的日志系统:

rust
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) 标记内部项,可以在不影响外部兼容性的前提下自由修改实现细节。