Boas Práticas de Padrões Rust

APIs difíceis de usar incorretamente codificam invariantes em tipos, usam erros explícitos e reservam mutabilidade interna para casos documentados.

Como Usar Esta Lista

• Aplique em revisões de design de API e scaffolding de crates de domínio.
• Emparelhe com as Diretrizes de API Rust.
• Verifique itens ao refatorar estilo Java/C# para Rust idiomático.

A - Tipos e API

• IDs Newtype e strings validadas. UserId, Email em vez de u64/String brutos na API pública.
• From/TryFrom para conversões. Não métodos parse_x ad hoc em todos os lugares.
• Builder ou construtor tipado para configuração complexa. Validação em um só lugar.
• Typestate ou enums para protocolos. Estados ilegais não representáveis onde é barato.
• Traits de extensão para ergonomia em tipos estrangeiros. Mantenha no módulo prelude.

B - Erros e Segurança

• Bibliotecas retornam Result, aplicativos registram contexto. Sem unwrap em caminhos públicos de bibliotecas.
• thiserror para erros de biblioteca, anyhow para binários. Política de workspace consistente.
• Documente # Panics, # Errors, # Safety em itens públicos. Seções rustdoc preenchidas.
• RAII para locks, arquivos, timers. Guardas de escopo em vez de chamadas manuais de limpeza.
• Evite grafos Rc<RefCell> sem diagrama. Prefira arenas ou propriedade única.

C - Idiomas de Desempenho

• Empreste e Cow antes de clone. Clone no limite da tarefa uma vez.
• Adaptadores de iterador em vez de loops de índice manuais, a menos que loops perfilados vençam.
• Pré-dimensionar coleções quando o tamanho é conhecido. with_capacity.
• Compartilhe dados imutáveis com Arc<str>/Arc<[u8]>. Não churn de Arc<String>.
• Mutabilidade interna: atômicos/Mutex documentados. Mutex Tokio em estado compartilhado assíncrono.

D - Assíncrono e Concorrência

• Estado compartilhado Arc + tokio::sync::Mutex ou canais. Não RefCell entre tarefas.
• Não bloqueie em assíncrono sem spawn_blocking. Documente limites do pool de threads.
• Semáforos para backpressure. Canais ilimitados são um sinal de problema.
• Handles de join aguardados ou desanexados intencionalmente. Sem tarefas órfãs vazadas.
• Padrão de desligamento gracioso. Tokens de cancelamento e esvaziamento.

E - Cultura de Revisão

• Checklist de PR cita escolha de padrão. Por que builder vs literal, por que newtype.
• Busca por anti-padrões na revisão. unwrap(, .clone() em arquivos "quentes" sinalizados.
• Exemplos em rustdoc compilam. Doctests em tipos de padrão.
• Padrões consistentes em toda a crate de domínio do workspace. Um tipo de erro, um estilo de ID.
• Refatore clones ao tocar no arquivo. Regra do escoteiro para desempenho.

FAQs

Relacionados

• Rust Patterns Basics
• Common Anti-Patterns
• 50 Rust Rules
• Architecture Best Practices

Versões de 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+.