Rust语义化版本检查工具cargo-semver-checks的使用，确保Rust库的兼容性与版本控制

Rust语义化版本检查工具cargo-semver-checks的使用，确保Rust库的兼容性与版本控制

快速开始

示例安装命令：

# 如果你已经使用`cargo-binstall`快速安装工具：
$ cargo binstall cargo-semver-checks

# 否则：
$ cargo install cargo-semver-checks --locked

# 在`cargo publish`前检查新版本是否符合SemVer规范：
$ cargo semver-checks

或者作为GitHub Action使用：

- name: Check semver
  uses: obi1kenobi/cargo-semver-checks-action@v2

cargo-semver-checks运行示例

完整示例

下面是一个展示如何使用cargo-semver-checks检查库API变更的完整示例：

  1. 创建Rust库项目：
$ cargo new my_lib --lib
$ cd my_lib
  1. 添加初始API（src/lib.rs）：
// 初始版本v1.0.0
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

pub struct Point {
    pub x: i32,
    pub y: i32,
}
  1. 提交并标记版本：
$ git add .
$ git commit -m "Initial API"
$ git tag v1.0.0
  1. 进行破坏性API变更（src/lib.rs）：
// 修改后的版本 - 破坏性变更
pub fn add(a: i32, b: i32) -> i64 {  // 返回类型变更
    (a + b) as i64
}

pub struct Point {
    pub x: i32,
    pub y: i32,
    pub z: i32,  // 新增字段
}
  1. 运行版本检查：
$ cargo semver-checks --baseline-rev v1.0.0
  1. 输出结果：
error: return type of function `add` changed from `i32` to `i64`
error: field `z` was added to struct `Point`

功能特点

  1. 检查API变更是否符合SemVer规范

  2. 支持多种基线版本指定方式：

    --baseline-version <X.Y.Z>    # 从注册表查找基准版本
--baseline-rev <REV>          # 从Git修订版本查找基准
--baseline-root <MANIFEST_ROOT> # 指定基准源代码目录
--baseline-rustdoc <JSON_PATH> # 使用指定的rustdoc JSON文件

  3. 支持条件编译配置：

    RUSTDOCFLAGS="--cfg some-option" cargo semver-checks

  4. 灵活的lint级别配置（Cargo.toml）：

[package.metadata.cargo-semver-checks.lints]
function_must_use_added = "warn"  # 将#[must_use]检查降级为警告

配置选项

完整配置示例（Cargo.toml）：

[workspace.metadata.cargo-semver-checks.lints]
# 将所有#[must_use]相关检查降级为警告
function_must_use_added = "warn"
inherent_method_must_use_added = "warn"
struct_must_use_added = "warn"
enum_must_use_added = "warn"
trait_must_use_added = "warn"
union_must_use_added = "warn"

# 改变特定检查的SemVer要求
function_missing = { level = "deny", required-update = "minor" }

与其他工具对比

  1. rust-semverver：基于rustc内部构建，已不再维护
  2. cargo-breaking：通过cargo expand和syn重新解析代码，已归档
  3. cargo-public-api：专注于API差异展示而非lint检查

cargo-semver-checks使用rustdoc的JSON输出进行分析，维护成本较低且性能更好。


1 回复

Rust语义化版本检查工具cargo-semver-checks使用指南

工具介绍

cargo-semver-checks是一个用于检查Rust库版本兼容性的工具，它可以帮助开发者确保他们的库遵循语义化版本控制(SemVer)规范。该工具能够检测公共API的变更，并判断这些变更是否符合当前版本号的语义要求。

安装方法

cargo install cargo-semver-checks

基本使用方法

检查当前项目的版本兼容性

cargo semver-checks check-release

这个命令会检查你的库从上一个发布版本到当前代码状态的变更，判断这些变更是否符合语义化版本控制规则。

检查特定版本间的兼容性

cargo semver-checks check --manifest-path ./Cargo.toml --baseline-rev v1.0.0

这会比较当前代码与标签v1.0.0时的代码差异。

高级用法

生成HTML报告

cargo semver-checks check-release --output-format html > report.html

忽略特定类型的变更

在Cargo.toml中添加配置：

[package.metadata.semver-checks]
ignore = [
    "added-public-impl",  # 忽略新增的公共实现
    "removed-pub-item"    # 忽略移除的公共项
]

作为CI/CD的一部分

可以在项目的CI流程中添加检查：

# GitHub Actions示例
- name: Check semver compliance
  run: cargo semver-checks check-release

示例输出解读

工具会输出类似这样的结果：

Found 3 changes:
- Breaking: Removed public function `old_function`
- Compatible: Added new public function `new_feature`
- Breaking: Changed signature of `important_method`

常见问题

  1. 误报处理：有时工具会报告实际上不破坏兼容性的变更，可以通过配置文件忽略
  2. 私有项变更：工具只关注公共API的变更，私有项的修改不会影响检查结果
  3. 版本号更新建议：工具会根据变更类型建议应该更新的版本号部分(主版本/次版本/修订号)

最佳实践

  1. 在发布新版本前运行检查
  2. 将检查集成到CI流程中
  3. 对于大型变更，使用--baseline-rev参数检查特定版本间的差异
  4. 定期检查依赖库的版本兼容性

通过使用cargo-semver-checks，你可以更自信地管理Rust库的版本发布，确保遵循语义化版本控制规范，减少对下游用户的影响。

完整示例demo

下面是一个完整的示例，展示如何使用cargo-semver-checks检查一个Rust项目的版本兼容性：

  1. 首先创建一个新的Rust库项目：
cargo new my_lib --lib
cd my_lib
  1. 添加一些简单的公共API（lib.rs）：
// 初始版本1.0.0的API
pub fn old_function() -> i32 {
    42
}

pub struct ImportantStruct;

impl ImportantStruct {
    pub fn important_method(&self) -> String {
        "hello".to_string()
    }
}
  1. 提交并打标签作为初始版本：
git add .
git commit -m "Initial version 1.0.0"
git tag v1.0.0
  1. 修改API（模拟版本升级）：
// 修改后的API
pub fn old_function() -> i32 {
    42
}

// 新增的公共函数
pub fn new_feature() -> bool {
    true
}

pub struct ImportantStruct;

impl ImportantStruct {
    // 修改了方法签名
    pub fn important_method(&self, prefix: &str) -> String {
        format!("{}-hello", prefix)
    }
}
  1. 安装并运行cargo-semver-checks：
cargo install cargo-semver-checks
cargo semver-checks check --baseline-rev v1.0.0
  1. 预期的输出结果：
Found 3 changes:
- Breaking: Changed signature of `ImportantStruct::important_method`
- Compatible: Added new public function `new_feature`
- Warning: Potential breakage - old_function exists but may have internal changes

Semver compatibility: MAJOR version change required (1.0.0 -> 2.0.0)
  1. 根据建议更新Cargo.toml版本号：
[package]
name = "my_lib"
version = "2.0.0"  # 因为有破坏性变更，需要升级主版本号
  1. 将检查集成到CI流程中（.github/workflows/ci.yml）：
name: CI
on: [push, pull_request]

jobs:
  semver_check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - name: Install cargo-semver-checks
        run: cargo install cargo-semver-checks
      - name: Check semver compliance
        run: cargo semver-checks check-release
回到顶部