Boas Práticas do Cargo

Fluxos de trabalho do Cargo reproduzíveis, rápidos e bem organizados mantêm as equipes Rust entregando sem surpresas de dependência ou loops de feedback lentos.

Como Usar Esta Lista

Aplique ao criar um novo repositório ou ao integrar um serviço em um workspace existente.
Use como um checklist de PR para alterações de manifesto (Cargo.toml, build.rs, perfis).
Combine com Gerenciamento de Dependências para manutenção contínua.

A - Estrutura do Projeto

Aplicações binárias fazem commit do Cargo.lock; bibliotecas documentam a política de lock. CI e deploys reproduzíveis para serviços.
Use um workspace quando tiver 2+ crates relacionadas. Um único lockfile e [workspace.dependencies] compartilhado.
Prefira o layout crates/ para monorepos em crescimento. Limites claros entre API, domínio e CLI.
Defina edition = "2024" e rust-version consistentemente. MSRV documentado no README e na CI.
Mantenha target/ e artefatos fora do git. Use .gitignore e cache de camadas Docker em vez disso.

B - Dependências

Fixe versões em [workspace.dependencies] uma vez. Membros usam workspace = true para evitar derivação.
Desabilite default-features ao otimizar o tempo de compilação. Opte explicitamente por crate.
Execute cargo audit (ou cargo deny) periodicamente. Avisos de segurança detectados precocemente.
Remova dependências não utilizadas; execute cargo tree -d após grandes atualizações. Duplicatas de versões principais inflacionam o tempo de compilação.
Evite dependências git em produção sem um rev fixado. Branches flutuantes quebram a reprodutibilidade.

C - Features e Perfis

Toda dependência opcional mapeia para uma feature nomeada. Consumidores habilitam a capacidade, não nomes de módulos internos.
Teste --no-default-features e --all-features na CI. Caminhos de código opcionais não se deterioram.
Perfil de release usa lto = "thin" e codegen-units ajustados. Meça antes de LTO pesado na CI.
Documente flags de feature no README. Inclua exemplos de linhas cargo build --features ....
Use perfis personalizados (release-fast) para iteração de performance local. Não enfraqueça o perfil de produção.

D - Scripts de Build e Ferramentas

build.rs lista rerun-if-changed para todas as entradas. Sem codegen obsoleto após edições de proto/config.
Prefira cargo check / clippy em loops de watch em vez de build completo. Feedback mais rápido para o desenvolvedor.
Instale cargo-nextest para workspaces grandes. Melhor paralelismo e relatórios de CI.
Use cargo expand ao depurar proc macros. Combine com Depurando Macros.
Cacheie o registro e target/ na CI. sccache ou cache do GitHub Actions para projetos Rust.

E - Publicação e Releases

cargo publish --dry-run antes de cada release. Conteúdo do tarball e metadados validados.
Semver e changelog para cada publicação no crates.io. Minors pré-1.0 podem ser breaking; documente a política.
Arquivos LICENSE correspondem ao campo license. Licença dupla MIT OU Apache-2.0 é o padrão.
docs.rs metadados habilitam all-features quando seguro. package.metadata.docs.rs configurado.
Yank releases ruins; nunca confie na exclusão. Siga com um release de patch e nota de aviso, se necessário.

FAQs

CI Mínima para projetos Cargo?

cargo fmt --check, cargo clippy --workspace -- -D warnings, cargo test --workspace, opcional cargo audit.

Raiz do Workspace sem pacote?

Workspace virtual é aceitável; defina default-members para ergonomia do cargo run.

Como acelerar builds limpos?

Divida crates "quentes", reduza features, use linker mold e cacheie dependências na CI.

Devo fazer commit do `Cargo.lock` para workspaces?

Sim, na raiz do workspace para aplicações; bibliotecas publicadas no crates.io frequentemente omitem locks de membros, exceto pela política da raiz do workspace que você documenta.

Quando `build.rs` é necessário?

Apenas para codegen, linking nativo ou descoberta de cfg. Não o use para tarefas melhor tratadas por xtask ou scripts de CI.

Como impor MSRV?

rust-version no manifesto mais um job cargo +1.97.0 check na matriz de CI.

E sobre vendoring?

cargo vendor para ambientes air-gapped ou restritos por política; adiciona sobrecarga de manutenção.

Como lidar com majors de dependência breaking?

PR de upgrade dedicado com revisão de changelog, cargo test --workspace e possível crate de shim de API.

Seções de patch são OK?

[patch.crates-io] apenas para forks temporários; remova quando os releases upstream corrigirem.

Como documentar comandos de build?

README com cargo run, flags de feature e variáveis de ambiente; link para .cargo/config.toml se não for o padrão.

Relacionados

Noções Básicas do Cargo - para começar
Workspaces - layout de monorepo
Gerenciamento de Dependências - atualizações e auditoria
Linting na CI - portões de qualidade

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.

Boas Práticas do Cargo

Fluxos de trabalho do Cargo reproduzíveis, rápidos e bem organizados mantêm as equipes Rust entregando sem surpresas de dependência ou loops de feedback lentos.

Como Usar Esta Lista

Aplique ao criar um novo repositório ou ao integrar um serviço em um workspace existente.
Use como um checklist de PR para alterações de manifesto (Cargo.toml, build.rs, perfis).
Combine com Gerenciamento de Dependências para manutenção contínua.

A - Estrutura do Projeto

Aplicações binárias fazem commit do Cargo.lock; bibliotecas documentam a política de lock. CI e deploys reproduzíveis para serviços.
Use um workspace quando tiver 2+ crates relacionadas. Um único lockfile e [workspace.dependencies] compartilhado.
Prefira o layout crates/ para monorepos em crescimento. Limites claros entre API, domínio e CLI.
Defina edition = "2024" e rust-version consistentemente. MSRV documentado no README e na CI.
Mantenha target/ e artefatos fora do git. Use .gitignore e cache de camadas Docker em vez disso.

B - Dependências

Fixe versões em [workspace.dependencies] uma vez. Membros usam workspace = true para evitar derivação.
Desabilite default-features ao otimizar o tempo de compilação. Opte explicitamente por crate.
Execute cargo audit (ou cargo deny) periodicamente. Avisos de segurança detectados precocemente.
Remova dependências não utilizadas; execute cargo tree -d após grandes atualizações. Duplicatas de versões principais inflacionam o tempo de compilação.
Evite dependências git em produção sem um rev fixado. Branches flutuantes quebram a reprodutibilidade.

C - Features e Perfis

Toda dependência opcional mapeia para uma feature nomeada. Consumidores habilitam a capacidade, não nomes de módulos internos.
Teste --no-default-features e --all-features na CI. Caminhos de código opcionais não se deterioram.
Perfil de release usa lto = "thin" e codegen-units ajustados. Meça antes de LTO pesado na CI.
Documente flags de feature no README. Inclua exemplos de linhas cargo build --features ....
Use perfis personalizados (release-fast) para iteração de performance local. Não enfraqueça o perfil de produção.

D - Scripts de Build e Ferramentas

build.rs lista rerun-if-changed para todas as entradas. Sem codegen obsoleto após edições de proto/config.
Prefira cargo check / clippy em loops de watch em vez de build completo. Feedback mais rápido para o desenvolvedor.
Instale cargo-nextest para workspaces grandes. Melhor paralelismo e relatórios de CI.
Use cargo expand ao depurar proc macros. Combine com Depurando Macros.
Cacheie o registro e target/ na CI. sccache ou cache do GitHub Actions para projetos Rust.

E - Publicação e Releases

cargo publish --dry-run antes de cada release. Conteúdo do tarball e metadados validados.
Semver e changelog para cada publicação no crates.io. Minors pré-1.0 podem ser breaking; documente a política.
Arquivos LICENSE correspondem ao campo license. Licença dupla MIT OU Apache-2.0 é o padrão.
docs.rs metadados habilitam all-features quando seguro. package.metadata.docs.rs configurado.
Yank releases ruins; nunca confie na exclusão. Siga com um release de patch e nota de aviso, se necessário.

FAQs

CI Mínima para projetos Cargo?

cargo fmt --check, cargo clippy --workspace -- -D warnings, cargo test --workspace, opcional cargo audit.

Raiz do Workspace sem pacote?

Workspace virtual é aceitável; defina default-members para ergonomia do cargo run.

Como acelerar builds limpos?

Divida crates "quentes", reduza features, use linker mold e cacheie dependências na CI.

Devo fazer commit do `Cargo.lock` para workspaces?

Sim, na raiz do workspace para aplicações; bibliotecas publicadas no crates.io frequentemente omitem locks de membros, exceto pela política da raiz do workspace que você documenta.

Quando `build.rs` é necessário?

Apenas para codegen, linking nativo ou descoberta de cfg. Não o use para tarefas melhor tratadas por xtask ou scripts de CI.

Como impor MSRV?

rust-version no manifesto mais um job cargo +1.97.0 check na matriz de CI.

E sobre vendoring?

cargo vendor para ambientes air-gapped ou restritos por política; adiciona sobrecarga de manutenção.

Como lidar com majors de dependência breaking?

PR de upgrade dedicado com revisão de changelog, cargo test --workspace e possível crate de shim de API.

Seções de patch são OK?

[patch.crates-io] apenas para forks temporários; remova quando os releases upstream corrigirem.

Como documentar comandos de build?

README com cargo run, flags de feature e variáveis de ambiente; link para .cargo/config.toml se não for o padrão.

Relacionados

Noções Básicas do Cargo - para começar
Workspaces - layout de monorepo
Gerenciamento de Dependências - atualizações e auditoria
Linting na CI - portões de qualidade

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.

Boas Práticas do Cargo

Buscar na documentação

Boas Práticas do Cargo