如何在Rust中用私有宏定义公共宏并解决可见性问题？

问题描述 #

想要实现公共宏a，其内部依赖私有宏b，但在测试代码及外部 crate 中，私有宏b的可见性限制导致公共宏a无法正常展开，出现编译错误。

示例代码 #

// 公共宏
#[macro_export]
macro_rules! a {
    () => {
        $crate::b!()
    };
}

// 仅内部使用的私有宏
macro_rules! b {
    () => {};
}

#[cfg(test)]
mod test {
    use super::a;

    #[test]
    fn test() {
        a!();
    }
}

编译错误输出 #

$ cargo test

警告：未使用的宏定义：`b`
  --> src/lib.rs:10:14
   |
10 | macro_rules! b {
   |              ^
   |
   = 注意：默认启用`#[warn(unused_macros)]`

警告：`my-crate`（lib）生成了1个警告
错误[E0433]：解析失败：在 crate 根目录中找不到`b`
  --> src/lib.rs:5:11
   |
5  |         $crate::b!()
   |                 ^ 在 crate 根目录中找不到`b`
...
20 |         a!();
   |         ---- 在此宏调用中
   |
   = 注意：此错误源自宏`a`（在夜间版本中，使用-Z macro-backtrace获取更多信息）

有关此错误的更多信息，请尝试`rustc --explain E0433`。
警告：`my-crate`（lib test）生成了1个警告（1个重复）
错误：由于之前的1个错误，无法编译`my-crate`（lib test）；已发出1个警告

解决方案 #

普通macro_rules!宏默认是当前模块私有，公共宏展开时会在调用上下文查找依赖的私有宏，导致解析失败。以下是三种有效解决方法：

方法1：导出私有宏并隐藏文档 #

将b宏标记为#[macro_export]导出到 crate 根，同时用#[doc(hidden)]隐藏它，确保外部无法通过文档发现和调用，但公共宏能正常访问：

#[macro_export]
macro_rules! a {
    () => {
        $crate::b!()
    };
}

// 导出但隐藏文档，仅作为公共宏的内部依赖
#[macro_export]
#[doc(hidden)]
macro_rules! b {
    () => {};
}

#[cfg(test)]
mod test {
    use super::a;

    #[test]
    fn test() {
        a!();
    }
}

方法2：内联私有宏逻辑 #

如果b宏逻辑简短，直接将其内容内联到公共宏a中，消除跨宏依赖：

#[macro_export]
macro_rules! a {
    () => {
        // 直接写入原b宏的实现逻辑
    };
}

#[cfg(test)]
mod test {
    use super::a;

    #[test]
    fn test() {
        a!();
    }
}

方法3：模块封装+重新导出 #

将私有宏放在内部模块中，再通过#[macro_export]导出并隐藏文档，既保证代码组织性，又限制外部访问：

#[macro_export]
macro_rules! a {
    () => {
        $crate::internal::b!()
    };
}

// 内部私有模块，存放依赖宏
mod internal {
    #[macro_export]
    #[doc(hidden)]
    macro_rules! b {
        () => {};
    }
}

#[cfg(test)]
mod test {
    use super::a;

    #[test]
    fn test() {
        a!();
    }
}

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