Clippy

一个用于捕捉常见错误并改进 Rust 代码的 lint 集合。

该 crate 包含超过 700 个 lint！

Lint 被分为多个类别，每个类别都有默认的 lint 级别。 你可以通过改变每个类别的 lint 级别来选择 Clippy 应该多大程度地烦扰帮助你。

类别	描述	默认级别
clippy::all	所有默认开启的 lint（正确性、可疑、风格、复杂度、性能）	warn/deny
clippy::correctness	完全错误或无用的代码	deny
clippy::suspicious	很可能是错误或无用的代码	warn
clippy::style	应该以更符合惯例的方式编写的代码	warn
clippy::complexity	以复杂方式完成简单任务的代码	warn
clippy::perf	可以写得更快的代码	warn
clippy::pedantic	较为严格或偶尔会有误报的 lint	allow
clippy::restriction	限制使用语言和库特性的 lint1	allow
clippy::nursery	仍在开发中的新 lint	allow
clippy::cargo	针对 cargo manifest 的 lint	allow

更多功能即将推出，如果你有想法请提交 issue！

restriction 类别绝对不应整体启用。其中包含的 lint 可能会对完全合理的代码进行检查，可能没有替代建议，并且可能与其他 lint（包括其他类别）相矛盾。在启用之前，应该逐个考虑这些 lint。

---

目录：

• 使用说明
• 配置
• 贡献
• 许可证

使用

以下是如何将 Clippy 作为 cargo 子命令使用的说明，适用于不使用 cargo 的项目或在 Travis CI 中使用。

作为 cargo 子命令（cargo clippy）

使用 Clippy 的一种方式是通过 rustup 将其安装为 cargo 子命令。

步骤 1：安装 Rustup

你可以在支持的平台上安装 Rustup。这将帮助我们安装 Clippy 及其依赖项。

如果你已经安装了 Rustup，请更新以确保你拥有最新的 Rustup 和编译器：

rustup update

步骤 2：安装 Clippy

一旦你安装了 rustup 和最新的稳定版本（至少 Rust 1.29），运行以下命令：

rustup component add clippy

如果提示找不到 clippy 组件，请运行 rustup self update。

步骤 3：运行 Clippy

现在你可以通过以下命令运行 Clippy：

cargo clippy

自动应用 Clippy 建议

Clippy 可以自动应用一些 lint 建议，就像编译器一样。注意 --fix 隐含 --all-targets，因此它可以修复尽可能多的代码。

cargo clippy --fix

工作空间

所有常用的工作空间选项都应该适用于 Clippy。例如，以下命令将在 example crate 上运行 Clippy：

cargo clippy -p example

与 cargo check 一样，这包括作为工作空间成员的依赖项，如路径依赖。 如果你只想在给定的 crate 上运行 Clippy，请使用 --no-deps 选项，如下所示：

cargo clippy -p example -- --no-deps

使用 clippy-driver

Clippy 也可以在不使用 cargo 的项目中使用。要做到这一点，请使用与 rustc 相同的参数运行 clippy-driver。例如：

clippy-driver --edition 2018 -Cpanic=abort foo.rs

注意，clippy-driver 是为仅运行 Clippy 而设计的，不应作为 rustc 的通用替代品。例如，clippy-driver 可能会产生未按预期优化的构建产物。

Travis CI

你可以像在本地使用 Clippy 一样将其添加到 Travis CI：

language: rust
rust:
  - stable
  - beta
before_script:
  - rustup component add clippy
script:
  - cargo clippy
  # 如果你希望在遇到警告时构建作业失败，请使用
  - cargo clippy -- -D warnings
  # 为了同时检查测试和非默认的 crate 特性，使用
  - cargo clippy --all-targets --all-features -- -D warnings
  - cargo test
  # 等等

注意，添加 -D warnings 将导致在代码中发现任何警告时构建失败。 这包括由 rustc 发现的警告（如 dead_code 等）。如果你想避免这种情况，只对 Clippy 警告引发错误， 请在代码中使用 #![deny(clippy::all)] 或在命令行中使用 -D clippy::all。 （你可以将 clippy::all 替换为你针对的特定 lint 类别。）

配置

允许/拒绝 lint

你可以在代码中添加选项来 allow/warn/deny Clippy lint：

• 使用 clippy lint 组（#![deny(clippy::all)]）来处理整个 Warn lint 集合。 注意 rustc 有额外的 lint 组。

• 使用 clippy 和 clippy::pedantic 两个 lint 组的所有 lint（#![deny(clippy::all)]、#![deny(clippy::pedantic)]）。请注意，clippy::pedantic 包含一些非常激进的 lint，容易出现误报。

• 仅使用某些 lint（例如 #![deny(clippy::single_match, clippy::box_vec)] 等）

• allow/warn/deny 可以使用 #[allow(...)] 等方式限制在单个函数或模块中。

注意：allow 表示在您的代码中抑制该 lint。使用 warn 时，lint 只会发出警告，而使用 deny 时，lint 会在触发您的代码时发出错误。错误会导致 Clippy 以错误代码退出，因此在 CI/CD 等脚本中很有用。

如果您不想在代码中包含 lint 级别，可以通过在运行 Clippy 时传递额外的标志来全局启用/禁用 lint：

要允许 lint_name，请运行

cargo clippy -- -A clippy::lint_name

要对 lint_name 发出警告，请运行

cargo clippy -- -W clippy::lint_name

这也适用于 lint 组。例如，您可以运行 Clippy，对所有启用的 lint 发出警告：

cargo clippy -- -W clippy::pedantic

如果您只关心单个 lint，可以允许所有其他 lint，然后明确对您感兴趣的 lint 发出警告：

cargo clippy -- -A clippy::all -W clippy::useless_format -W clippy::...

配置某些 lint 的行为

某些 lint 可以在名为 clippy.toml 或 .clippy.toml 的 TOML 文件中进行配置。它包含基本的 变量 = 值 映射，例如

avoid-breaking-exported-api = false
disallowed-names = ["toto", "tata", "titi"]

配置表包含所有配置值、它们的默认值以及受影响的 lint 列表。每个可配置的 lint也包含有关这些值的信息。

对于具有默认值的列表类型配置，例如 disallowed-names，您可以使用特殊值 ".." 来扩展默认值，而不是替换它们。

# disallowed-names 的默认值为 ["foo", "baz", "quux"]
disallowed-names = ["bar", ".."] # -> ["bar", "foo", "baz", "quux"]

注意

clippy.toml 或 .clippy.toml 不能用于允许/拒绝 lint。

要停用"有关更多信息，请访问 lint-link"消息，您可以定义 CLIPPY_DISABLE_DOCS_LINKS 环境变量。

指定最低支持的 Rust 版本

打算支持旧版本 Rust 的项目可以通过在 Clippy 配置文件中指定最低支持的 Rust 版本（MSRV）来禁用与较新功能相关的 lint。

msrv = "1.30.0"

或者，可以使用 Cargo.toml 中的 rust-version 字段。

# Cargo.toml
rust-version = "1.30"

MSRV 也可以作为属性指定，如下所示。

#![feature(custom_inner_attributes)]
#![clippy::msrv = "1.30.0"]

fn main() {
  ...
}

在指定 MSRV 时，您也可以省略补丁版本，因此 msrv = 1.30 等同于 msrv = 1.30.0。

注意：custom_inner_attributes 是一个不稳定的特性，因此必须显式启用。

可以在此处找到识别此配置选项的 lint。

贡献

如果您想为 Clippy 做出贡献，可以在 CONTRIBUTING.md 中找到更多信息。

许可证

版权所有 2014-2024 Rust 项目开发者

根据 Apache 许可证 2.0 版 <LICENSE-APACHE 或 https://www.apache.org/licenses/LICENSE-2.0> 或 MIT 许可证 <LICENSE-MIT 或 https://opensource.org/licenses/MIT> 授权， 由您选择。除非符合这些条款，否则不得复制、修改或分发项目中的文件。

Footnotes

1. restriction lint 的一些使用场景包括：

   • 严格的编码风格（如 clippy::else_if_without_else）。
   • CI 中的额外限制（如 clippy::todo）。
   • 防止在某些函数中出现 panic（如 clippy::unwrap_used）。
   • 仅在代码的一个子集上运行 lint（如在模块上使用 #[forbid(clippy::float_arithmetic)]）。
   ↩