如何禁止Rust项目examples示例代码访问库内部依赖？

Cargo默认会将[dependencies]下声明的所有依赖对examples、集成测试、benchmark等开发类target可见，这是框架的默认设计，没有提供一键关闭的全局开关，可通过以下三种方案实现内部依赖的隔离，让示例代码非法引用内部依赖时直接触发编译报错：

方案1：dep:前缀+依赖重命名（轻量方案，Rust 1.60+稳定支持） #

默认写法下Cargo会为每个依赖生成与包名同名的全局引用标识，所有target都能直接引用。使用dep:前缀声明内部依赖后，Cargo不会自动暴露依赖的原生包名，仅在库内部代码中可访问：

• 修改Cargo.toml的依赖声明，给内部依赖加私有别名，使用dep:前缀阻断原生包名暴露

[dependencies]
# 内部实现用的nalgebra，重命名为_impl后缀的私有别名，不会暴露nalgebra原名
dep:nalgebra = { version = "0.31.0", rename = "na_impl" }

• 在库内部代码（src/目录下）使用别名引用依赖即可

// src/lib.rs 内部可以正常使用
use na_impl as na;

• 此时示例代码中如果写use nalgebra as na;会直接触发unresolved import 'nalgebra'的编译错误，达到隔离效果。

注意：该方案下示例代码仍可通过你设置的别名na_impl引用到内部依赖，适合对隔离要求不极端的场景，如果需要完全杜绝别名泄漏，使用下面的Workspace方案。

方案2：Workspace结构隔离（最严格，零依赖泄漏） #

如果需要100%保证内部依赖不会被示例、集成测试感知，可以把项目拆为多crate workspace结构：

• 新建私有内部crate（比如叫my_lib_core），所有内部实现依赖（如nalgebra）都声明在这个crate下，这个crate配置为不对外发布
• 对外发布的主crate仅依赖内部crate，将需要公开的API通过pub use重新导出，主crate自身的[dependencies]中完全不引入nalgebra这类实现细节依赖
• 所有示例代码放在主crate的examples目录下

该结构下示例代码的编译环境中完全不存在nalgebra相关的crate引用，任何直接调用内部依赖的代码都会直接编译失败，不需要额外配置检查规则。

方案3：Clippy Lint拦截（零结构改动，适合存量项目） #

如果不想调整现有项目结构，可以使用Clippy提供的disallowed_pathslint拦截非法引用：

• 在Cargo.toml中添加lint配置，将所有内部依赖加入禁止引用列表

[lints.clippy]
disallowed_paths = "deny"
[lints.clippy.disallowed_paths]
paths = [
    { path = "nalgebra", reason = "nalgebra为内部实现依赖，禁止在示例、测试代码中直接引用" }
]

• 在库的入口文件src/lib.rs顶部添加lint豁免，允许内部代码正常使用依赖

// src/lib.rs 顶部
#![allow(clippy::disallowed_paths)]

配置完成后，示例、集成测试代码中只要出现对nalgebra的引用，就会直接触发编译报错，阻断违规代码合入。

不建议仅靠开发者自觉约束示例代码写法，以上三种方案都可以在CI阶段自动完成校验，从编译层面阻断违规用法。

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