Módulos e Crates: Melhores Práticas

Como Usar Esta Lista

• Aplique antes de dividir ou mesclar crates em um workspace.
• Revise as exportações públicas de lib.rs a cada lançamento.

A - Layout de Módulos

• Mantenha main.rs enxuto; lógica em lib.rs. Núcleo da biblioteca testável.
• Agrupe por domínio (autenticação, faturamento), não apenas por camada. Encontre arquivos por funcionalidade.
• Limite reexportações pub use a um prelúdio curado. Evite exportar tudo.
• Prefira caminhos crate:: em código de biblioteca em vez de super:: profundos. Seguro para refatoração.
• Um módulo por arquivo quando o arquivo crescer além de ~300 linhas. Divida cedo.

B - Visibilidade

• Privado por padrão; escale para pub deliberadamente. Superfície de API menor.
• Use pub(crate) para API interna entre módulos. Não visível externamente.
• Construtores validam invariantes; campos privados. Encapsulamento.
• Documente #[non_exhaustive] em enums públicos extensíveis. Semver.
• Oculte módulos de implementação; exponha apenas traits/tipos. Use pub mod com moderação.

C - Workspaces e Crates

• Centralize as versões de dependência em [workspace.dependencies]. Uma única verdade para o lockfile.
• CI executa cargo test --workspace --all-features. Capture lacunas de cfg.
• Publique apenas as crates pretendidas; a raiz do workspace virtual não é publicada. Política do crates.io.
• Force a direção da dependência (o domínio não tem axum/sqlx). Limites hexagonais.
• Flags de recursos documentadas no README e comentários do Cargo.toml.

D - API Pública

• Semver e changelog para crates publicadas. Disciplina de quebra de compatibilidade.
• missing_docs em itens públicos. Completude do rustdoc.
• Exemplos em examples/ compilam na CI. cargo test --examples.
• MSRV no campo rust-version. Expectativas do consumidor.
• Evite vazar caminhos pub de módulos internos na documentação. Use #[doc(inline)] com cuidado no rustdoc.

FAQs

Relacionados

• Projetando uma API Pública
• Workspaces
• Melhores Práticas do Cargo
• Melhores Práticas de Rust Não Seguro

Versões da Stack: 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+.