cargo-public-api

列出和比较 Rust 库 crate 在不同版本和提交之间的公共 API。通过 CI 或 CLI 检测破坏性 API 变化和 semver 违规。依赖于并自动构建 rustdoc JSON，需要安装 Rust 夜间工具链的最近版本。

安装

使用较新的稳定 Rust 工具链安装 cargo public-api 子命令

cargo +stable install cargo-public-api --locked

确保已安装 nightly-2024-07-05 或更高版本（无需是活动工具链），以便 cargo public-api 可以为您构建 rustdoc JSON

rustup install nightly --profile minimal

用法

列出公共 API

此示例列出 regex crate 的公共 API。首先克隆仓库

git clone https://github.com/rust-lang/regex ; cd regex

现在我们可以通过运行以下命令列出 regex 的公共 API

cargo public-api

这将打印出 regex 的公共 API，每行一个公共项

比较公共 API

… 与特定已发布版本

将 regex crate 的公共 API 与当前目录中的 已发布版本 1.6.0 在 crates.io 上进行比较

cargo public-api diff 1.6.0

… 与最新已发布版本

cargo public-api diff latest

… 之间的 Git 提交

cargo public-api diff ref1..ref2

… 作为 CI 检查

通过在CI中运行常规的cargo test命令，您将能够

• 防止意外更改您的公共API
• 审查有意进行的公共API更改的diff

首先，将推荐的库的最新版本添加到您的[dev-dependencies]

cargo add --dev \
    rustup-toolchain \
    rustdoc-json \
    public-api \
    expect-test

然后，将以下测试添加到您的项目中。作为以下测试代码的作者，我将其关联到CC0，并在法律允许的范围内放弃所有版权及相关或邻近的权利

#[test]
fn public_api() {
    // Install a compatible nightly toolchain if it is missing
    rustup_toolchain::install(public_api::MINIMUM_NIGHTLY_RUST_VERSION).unwrap();

    // Build rustdoc JSON
    let rustdoc_json = rustdoc_json::Builder::default()
        .toolchain(public_api::MINIMUM_NIGHTLY_RUST_VERSION)
        .build()
        .unwrap();

    // Derive the public API from the rustdoc JSON
    let public_api = public_api::Builder::from_rustdoc_json(rustdoc_json)
        .build()
        .unwrap();

    // Assert that the public API looks correct
    expect_test::expect_file!["public-api.txt"].assert_eq(&public_api.to_string());
}

在您第一次运行测试之前，需要祝福当前公共API

UPDATE_EXPECT=1 cargo test public_api

这将在您的项目中创建一个tests/public-api.txt文件，您需要将其与您的其他项目文件一起使用git add命令。每次您更改公共API时，都需要使用上述命令再次祝福它。如果您忘记祝福，测试将失败，并提供祝福的说明。

输出更安静

为了完整性，属于 blanket Implementations 、 Auto Trait Implementations 和 Auto Derived Implementations 的项目，例如

• impl<T, U> Into<U> for T 其中U: From<T>
• impl Syncfor ...
• impl Debug for ... / #[derive(Debug)]

默认情况下包含在公共项目列表中。使用

• --omit blanket-impls
• --omit auto-trait-impls
• --omit auto-derived-impls

分别从输出中省略此类项目，使其变得不那么嘈杂

cargo public-api --omit blanket-impls,auto-trait-impls,auto-derived-impls

为了方便，您还可以使用-s (--simplified)来达到同样的效果。这是上述命令的简短形式

cargo public-api -sss

兼容性矩阵

更改日志

请参阅CHANGELOG.md。

贡献

请参阅CONTRIBUTING.md。

维护者

• Enselic
• douweschulte
• Emilgardis