cargo-check-external-types

cargo-check-external-types 是一个用于Rust库作者的静态分析工具，用于设置和验证哪些其他库的类型可以暴露在其公共API中。这有助于确保依赖项的破坏性更改不会强制使用它的库进行破坏性更改。

该工具有两种输出格式，以覆盖不同的用例

• errors（默认）：为在公共API中暴露的每个类型输出错误消息，如果至少有一个错误，则退出状态为1。这对于持续集成非常有用。
• markdown-table：以Markdown表格的形式输出类型暴露的位置。这旨在作为现有项目的发现工具。

该工具有一个可选的配置文件，其中可以显式允许类型。

示例输出

测试套件有一个依赖于某些外部类型的Rust库。当在没有配置的情况下对此库运行此工具时，它会在公共API中每个外部类型的出现处发出错误。

当提供了配置文件时，允许的外部类型将不再出现在输出中。

当输出格式设置为 markdown-table 时，将输出一个 外部类型表。

使用方法

重要：此工具需要安装 Rust 的夜间构建版本，因为它依赖于 rustdoc JSON 输出，该输出尚未稳定。它最后在 nightly-2024-05-01 上进行了测试。

要从本 README 路径安装，请运行以下命令

cargo install --locked cargo-check-external-types

然后，在您的库 crate 路径中运行

cargo +nightly check-external-types

如果公共 API 中使用了任何外部类型，这将产生错误。这本身并不非常有用，因此可以在您的 crate 的 Cargo.toml 中提供配置以允许某些类型。例如，我们可以通过在 crate 的 Cargo.toml 中添加以下元数据来允许 bytes 中的任何类型

[package.metadata.cargo_check_external_types]
allowed_external_types = ["bytes::*"]

或者，如果您愿意，可以创建一个单独的配置文件，其内容如下

allowed_external_types = [
    "bytes::*",
]

将此文件保存到您的项目中的某个位置（在这个例子中，我们选择名称 external-types.toml），然后使用以下命令运行该命令

cargo +nightly check-external-types --config external-types.toml

如果同时提供了 Cargo.toml 包元数据部分和 --config 标志，则将使用 --config 标志而不是包元数据。

注意事项

当在 [doc(hidden)] 模块中声明的公共类型和模块从公共模块重新导出时，它们不会检查外部类型。这是因为它们在 RustDoc 索引中的记录方式。当此工具遇到此类类型和模块时，将记录一条警告。

安全

有关更多信息，请参阅 CONTRIBUTING。

许可证

本项目根据 Apache-2.0 许可证授权。