Rust库如何仅对外暴露私有泛型类型的特定具象变体？

解决方案 #

有两种常用的实现方案可以满足你的需求，不需要重复定义结构体代码：

方案1：Newtype封装（推荐，严格隔离API） #

这是Rust中最常用的类型封装方案，完全隐藏内部泛型实现，对外仅暴露非泛型的Bar类型：

1. 首先将原有的泛型Foo改为私有，去掉pub标记
2. 定义公开的非泛型元组结构体Bar，将Foo<u32>作为其唯一的私有内部字段
3. 公开方法可以手动转发或者通过宏批量转发，避免重复代码

代码示例：

// 内部泛型结构体，完全私有，不会暴露到公开API中
struct Foo<X> {
    x: X,
    // 其余原有字段保持不变
}

// 对外公开的非泛型类型，文档中不会出现任何泛型相关信息
pub struct Bar(Foo<u32>);

// 原有的公开函数返回Bar类型即可
pub fn foo() -> Bar {
    // 内部逻辑构造Foo<u32>后封装为Bar返回
    Bar(Foo { x: 123 })
}

// 转发Foo<u32>上的公开方法
impl Bar {
    // 示例：转发get_x方法
    pub fn get_x(&self) -> u32 {
        self.0.x
    }

    // 其余需要公开的方法都可以按此模式转发
    // 如果方法数量多，可以用声明宏批量减少重复代码
}

// 批量转发方法的宏示例，可根据需要扩展支持参数、可变引用等场景
macro_rules! forward_methods {
    ($( $method:ident -> $ret:ty ),* $(,)?) => {
        $(
            pub fn $method(&self) -> $ret {
                self.0.$method()
            }
        )*
    };
}

impl Bar {
    // 批量调用宏转发方法
    forward_methods! {
        get_x -> u32,
        // other_method -> String,
    }
}

该方案的优势是API隔离完全彻底，用户完全无法接触到内部的泛型Foo结构，不会出现意料之外的API泄露。

方案2：文档隐藏+类型别名（零成本适配） #

如果你不需要严格禁止用户访问内部Foo结构，只需要简化公开文档，可以通过文档属性实现零修改成本的适配：

1. 给泛型Foo添加#[doc(hidden)]属性，将其从公开文档中隐藏
2. 给Bar类型别名添加#[doc(no_inline)]属性，避免cargo doc自动展开别名

代码示例：

// 虽然标记为pub，但#[doc(hidden)]会让它不出现在公开文档中
#[doc(hidden)]
pub struct Foo<X> {
    x: X,
    // 其余原有字段保持不变
}

// no_inline属性避免文档展开别名，用户看到的只有Bar类型
#[doc(no_inline)]
pub type Bar = Foo<u32>;

// 原有函数无需修改返回值，文档中会显示返回Bar类型
pub fn foo() -> Bar {
    Foo { x: 123 }
}

该方案的优势是完全不需要修改原有逻辑，也不需要手动转发方法，原有Foo<u32>上的所有公开方法都可以直接在Bar实例上调用。缺点是Foo本质上还是公开类型，用户如果刻意导入仍然可以使用。

内容的提问来源于stack exchange，提问作者Florian Brucker