cargo-public-api/cargo-public-api

# cargo-public-api 列出并比对 Rust library crates 在不同版本和提交之间的公开 API。通过 CI 或 CLI 检测破坏性 API 变更和 semver 违规。依赖并自动构建 [rustdoc JSON](https://github.com/rust-lang/rust/issues/76578)，因此必须安装近期版本的 Rust nightly 工具链。 # 安装 使用近期的常规 **stable** Rust 工具链安装 `cargo public-api` 子命令： ``` cargo +stable install cargo-public-api ``` 确保已安装 **nightly-2025-08-02** 或更高版本（无需是当前活动工具链），以便 `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 中的每个公开项占一行： ## 比对公开 API ### … 与特定已发布版本 要将**当前目录**下 `regex` crate 的公开 API 与 [crates.io](https://crates.io/crates/regex/1.6.0) 上**已发布的 1.6.0 版本**进行比对： ``` 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 差异 首先将推荐库的最新版本添加到您的 `[dev-dependencies]` 中： ``` cargo add --dev \ rustup-toolchain \ rustdoc-json \ public-api ``` 然后将以下测试添加到您的项目中。作为以下测试代码的作者，我在此将其与 [CC0](https://creativecommons.org/publicdomain/zero/1.0/) 关联，并在法律允许的范围内放弃对其的所有版权及相关权利： ``` #[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 rustdoc JSON. let public_api = public_api::Builder::from_rustdoc_json(rustdoc_json) .build() .unwrap(); // Assert that the public API matches the latest snapshot. // Run with env var `UPDATE_SNAPSHOTS=yes` to update the snapshot. public_api.assert_eq_or_update("./tests/snapshots/public-api.txt"); } ``` 在首次运行测试之前，您需要创建当前公开 API 的快照： ``` UPDATE_SNAPSHOTS=yes cargo test ``` 这会在您的项目中创建一个 `tests/public-api.txt` 文件，您需要将其与其他项目文件一起执行 `git add`。然后，常规的 ``` cargo test ``` 将会在您的公开 API 被意外或故意更改时失败。再次运行 ``` UPDATE_SNAPSHOTS=yes cargo test ``` 以更新公开 API 快照并审查 git diff。 ## 减少噪音输出 为了完整性，属于 _Blanket Implementations_、_Auto Trait Implementations_ 和 _Auto Derived Implementations_ 的项，例如 * `impl Into for T where U: From` * `impl Sync for ...` * `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 ``` # 兼容性矩阵 | 版本 | 支持的 rustdoc JSON 输出版本 | | ---------------- | --------------------------------------- | | 0.50.x — 0.51.x | nightly-2025-08-02 — | | 0.49.x | nightly-2025-07-17 — nightly-2025-08-01 | | 0.48.x | nightly-2025-06-22 — nightly-2025-07-16 | | 0.47.x | nightly-2025-03-24 — nightly-2025-06-21 | | 0.46.x | nightly-2025-03-16 — nightly-2025-03-23 | | 0.45.x | nightly-2025-03-14 — nightly-2025-03-15 | | 更早的版本 | 见 [此处](https://github.com/cargo-public-api/cargo-public-api/blob/main/scripts/release-helper/src/version_info.rs) | # 贡献 参见 [CONTRIBUTING.md](./docs/CONTRIBUTING.md)。 ## 维护者 - [Enselic](https://github.com/Enselic) - [douweschulte](https://github.com/douweschulte) - [Emilgardis](https://github.com/Emilgardis) # 商标声明 “Rust” 和 “Cargo” 是 Rust Foundation 的商标。本项目未隶属于、未由 Rust Project 或 Rust Foundation 认可，也未与之有关联。