Configurando o Clippy
clippy.toml (e Cargo.toml [lints.clippy]) ajustam thresholds, métodos proibidos e macros de terceiros para que o Clippy corresponda aos padrões da sua equipe.
Receita
# clippy.toml
cognitive-complexity-threshold = 25
disallowed-methods = [
{ path = "std::env::var", reason = "use crate config" },
]Quando usar isso: Banir unwrap em aplicativos, aumentar limites de complexidade ou documentar APIs proibidas.
Exemplo de Trabalho
# clippy.toml na raiz do workspace
avoid-breaking-exported-api = false
too-many-lines-threshold = 120
disallowed-types = [
{ path = "std::sync::Mutex", reason = "use parking_lot::Mutex or tokio::sync::Mutex" },
]# crates/api/Cargo.toml
[lints.clippy]
unwrap_used = "deny"
expect_used = "deny"cargo clippy --workspace -- -D warningsO que isso demonstra:
clippy.tomlna raiz do workspace se aplica a todos os membros[lints.clippy]por crate para bins mais rigorosos vs libsdisallowed-methodsfalha a compilação com motivo personalizado- Thresholds reduzem falsos positivos em manipuladores grandes
Mergulho Profundo
Chaves Úteis do clippy.toml
| Chave | Propósito |
|---|---|
cognitive-complexity-threshold | Limite de complexidade da função |
too-many-arguments-threshold | Nível de aviso de aridade |
disallowed-names | Banir nomes de variáveis como foo |
msrv | Evitar lints que exigem Rust mais recente que MSRV |
Macros de Terceiros
third-party = { yaml = true }- Ajuda o clippy a entender macros DSL
- Reduz falsos positivos em macros
serde,tracing
Armadilhas
clippy.tomlno diretório errado - configurações ignoradas. Correção: coloque na raiz do workspace ou na raiz do crate de onde o Clippy busca para cima a partir do manifesto do pacote.- Proibir demais - bloqueia usos legítimos do std. Correção: estreite os caminhos; permita em testes via
cfg(test). - Incompatibilidade MSRV - clippy sugere APIs que você não pode usar. Correção: defina
msrv = "1.97.0"emclippy.toml. - Thresholds diferentes por crate sem substituição - um tamanho não serve bem. Correção:
clippy.tomlaninhado no crate membro. - Confiar nos padrões após atualização do Rust - novos lints aparecem. Correção: revisão do changelog ao atualizar a toolchain.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
Apenas [lints.clippy] | Permitir/negar simples | Precisa de lista de métodos proibidos |
Apenas #[allow] | Exceções únicas | APIs proibidas em toda a organização |
Crate de lint rustc personalizado | Políticas extremas | Equipes de aplicativos padrão |
FAQs
Localização do `clippy.toml` vs `rustfmt.toml`?
Mesma descoberta: diretório do pacote, depois ancestrais até a raiz do workspace.
Como banir unwrap em todo o projeto?
unwrap_used = "deny" nos manifestos do crate do aplicativo; permitir em módulos #[cfg(test)].
Formato do `disallowed-methods`?
Array de entradas { path = "...", reason = "..." }.
O `msrv` em `clippy.toml` impõe MSRV?
Ele filtra sugestões; ainda defina rust-version em Cargo.toml para imposição do cargo.
Threshold de complexidade para handlers?
Handlers Axum podem ser mais longos; aumente o threshold ou extraia helpers em vez de permitir genericamente.
Clippy para testes?
Mesma configuração; relaxe lints específicos dentro de mod tests com permite internos.
Workspace com políticas mistas?
clippy.toml rigoroso na raiz; [lints] por crate relaxam para crate legado durante a migração.
Como testar mudança de configuração?
Introduza violação intencional; confirme que o clippy falha com o nome do lint esperado.
YAML de terceiros para tracing?
Habilite em clippy.toml para reduzir o ruído da expansão de macros.
Atualizar `clippy.toml` ao atualizar o clippy?
Revise as notas de lançamento ao atualizar o Rust; novos lints podem precisar de ajustes de threshold.
Relacionados
- Clippy - executando clippy
- Níveis e Atributos de Lint - negar/permitir
- Linting em CI - imposição
- Padrões de Codificação - padrões da equipe
Versões da Pilha: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.