Clippy

用于捕获常见错误并改进 Rust 代码的一系列 lint 规则。

本 crate 包含超过 800 条 lint 规则！

Lint 规则按类别划分，每个类别都有一个默认的 lint 级别。你可以通过按类别更改 lint 级别来选择 Clippy 应该在多大程度上 烦扰 帮助你。

类别	描述	默认级别
clippy::all	所有默认启用的 lint（正确性、可疑性、样式、复杂度、性能）	warn/deny
clippy::correctness	完全错误或无用的代码	deny
clippy::suspicious	很可能错误或无用的代码	warn
clippy::style	应以更符合 Rust 风格的方式编写的代码	warn
clippy::complexity	以复杂方式实现简单功能的代码	warn
clippy::perf	可编写为运行更快的代码	warn
clippy::pedantic	规则相当严格或偶尔会误报的 lint	allow
clippy::restriction	禁止使用语言和库功能的 lint[1]	allow
clippy::nursery	仍在开发中的新 lint	allow
clippy::cargo	针对 cargo 清单的 lint	allow

未来还会添加更多规则，如果你有想法，请提交 issue！

需要特别强调的是，不应整体启用 restriction 类别。其中包含的 lint 可能会针对完全合理的代码发出警告，可能没有替代建议，并且可能与其他 lint（包括其他类别）相矛盾。启用这些 lint 应逐案考虑。

---

目录：

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

使用方法

以下是将 Clippy 用作 cargo 子命令、在不使用 cargo 的项目中或在 Travis CI 中使用 Clippy 的说明。

作为 cargo 子命令（cargo clippy）

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

步骤 1：安装 Rustup

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

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

rustup update

步骤 2：安装 Clippy

安装好 rustup 和最新的稳定版 Rust（至少 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
  # if you want the build job to fail when encountering warnings, use
  - cargo clippy -- -D warnings
  # in order to also check tests and non-default crate features, use
  - cargo clippy --all-targets --all-features -- -D warnings
  - cargo test
  # etc.

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

配置

允许/拒绝 Lint

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

• 使用 clippy lint 组来控制所有 Warn 级别的 lint（#![deny(clippy::all)]）。请注意，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 组。例如，你可以在启用所有 lint 的警告的情况下运行 Clippy：

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 文件中进行配置。该文件包含基本的 variable = value 映射，例如

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

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

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

# default of disallowed-names is ["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 中找到更多信息。

许可证

版权所有 (c) Rust 项目贡献者

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

---

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

   • 严格的编码风格（例如 clippy::else_if_without_else）。
   • CI 上的额外限制（例如 clippy::todo）。
   • 防止在特定函数中发生 panic（例如 clippy::unwrap_used）。
   • 仅在部分代码上运行 lint（例如在模块上使用 #[forbid(clippy::float_arithmetic)]）。
   ↩︎