写给rust开发者：一文了解cargo-deny项目

1. 项目背景

cargo-deny 是由 Embark Studios 开发的一个 Rust 工具，托管在 GitHub 上（EmbarkStudios/cargo-deny）。它是一个 Cargo 插件，旨在帮助开发者管理 Rust 项目的依赖，确保依赖符合特定的要求和期望。Rust 生态以其丰富的 crates（库）而著称，但随着项目规模扩大，依赖管理变得复杂，cargo-deny 应运而生，提供了依赖审查和 Lint 功能。

该工具最初是为 Embark Studios 内部使用设计的，后来开源并得到了社区的支持。它特别适合需要关注依赖安全性、许可证合规性或代码质量的开发者，是 Rust 项目持续集成 (CI) 流水线中的理想选择。

2. 核心功能

cargo-deny 提供了以下几个主要检查功能，分别对应不同的依赖管理需求：

• 许可证检查（Licenses） ：验证每个依赖的许可证是否符合你的要求，支持自定义允许或拒绝的许可证列表。
• 禁令检查（Bans） ：禁止特定 crates 或处理同一 crate 的多个版本问题。
• 安全建议检查（Advisories） ：通过 RustSec 数据库检测依赖中的已知安全漏洞或被标记为未维护的 crates。
• 来源检查（Sources） ：确保依赖仅来自受信任的来源（如指定的注册表或 Git 仓库）。

这些功能通过配置文件 deny.toml 进行定制，使其灵活适应不同项目的需求。

3. 安装方法

安装 cargo-deny 需要 Rust 环境已就绪，然后运行以下命令：

cargo install --locked cargo-deny

安装完成后，验证是否成功：

cargo deny --version

若显示版本号，安装即完成。

4. 基本使用方法

cargo-deny 的核心命令是 cargo deny check，用于执行检查。以下是基本用法：

4.1 初始化配置文件

首次使用时，运行以下命令生成默认配置文件 deny.toml：

cargo deny init

这会创建一个模板配置文件，你可以根据需求修改。

4.2 执行所有检查

在项目根目录运行：

cargo deny check

这会依次执行许可证、禁令、安全建议和来源检查，并输出结果。

4.3 指定特定检查

如果只想运行某项检查，可以指定参数：

cargo deny check licenses  # 检查许可证
cargo deny check bans      # 检查禁令
cargo deny check advisories # 检查安全建议

4.4 查看许可证列表

列出项目中所有依赖的许可证：

cargo deny list

5. 配置详解

deny.toml 是 cargo-deny 的核心配置文件，以下是常见配置项示例：

5.1 许可证配置

[licenses]
unlicensed = "deny"  # 未指定许可证的 crate 报错
allow = ["MIT", "Apache-2.0"]  # 允许的许可证
deny = ["GPL-3.0"]  # 禁止的许可证

5.2 禁令配置

[bans]
multiple-versions = "warn"  # 检测到多版本时警告
deny = [{ crate = "openssl", reason = "use rustls instead" }]  # 禁止特定 crate

5.3 安全建议配置

[advisories]
ignore = ["RUSTSEC-2020-0001"]  # 忽略特定安全建议

5.4 来源配置

[sources]
unknown-registry = "deny"  # 禁止未知注册表的依赖
allow-registry = ["https://github.com/rust-lang/crates.io-index"]  # 允许的注册表

6. 高级用法

6.1 在 CI 中使用

cargo-deny 非常适合集成到 CI 流程中。例如，在 GitHub Actions 中：

name: CI
on: [push, pull_request]
jobs:
  cargo-deny:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: EmbarkStudios/cargo-deny-action@v1
        with:
          command: check

6.2 处理特殊情况

如果某个 crate 未正确声明许可证，可以手动澄清：

[[licenses.clarify]]
crate = "ring"
expression = "ISC"
license-files = [{ path = "LICENSE", hash = 0x001c7e6c }]

7. 实用建议

• 定期更新：运行 cargo install --force cargo-deny 更新到最新版本，以获取新功能和修复。
• 结合其他工具：搭配 cargo-audit 或 cargo-outdated 使用，全面管理依赖。
• 调试问题：检查输出中的依赖路径图，帮助定位问题来源。
• 社区资源：参考官方文档（embarkstudios.github.io/cargo-deny）或 GitHub 仓库的 Issues 获取帮助。

8. 示例项目

假设你想检查一个项目的许可证合规性：

1. 安装并初始化：

cargo install --locked cargo-deny
cargo deny init

2. 编辑 deny.toml，只允许 MIT 许可证：

[licenses]
allow = ["MIT"]

3. 运行检查：

cargo deny check licenses

如果有非 MIT 许可证的依赖，工具会报错并提示依赖路径。

9. 总结

cargo-deny 是一个功能强大且易用的 Rust 依赖管理工具，通过检查许可证、安全性、禁令和来源，帮助开发者维护项目质量。它的配置灵活，集成方便，非常适合个人项目和团队开发。希望这份文档能为你的 Rust 开发之旅提供便利