Boas Práticas de Structs & Enums

Projete tipos de dados para que invariantes vivam em um só lugar e o compilador ajude a aplicá-los.

Como Usar Esta Lista

• Aplique ao projetar novos tipos de domínio antes de escrever a lógica.
• Revise durante Pull Requests que adicionam flags bool ou "sopa" de Option.
• Use em conjunto com Modelagem de Domínio com Tipos.

A - Design de Structs

• Prefira structs pequenas e focadas em vez de "god objects". Divida quando os campos se agruparem em ciclos de vida distintos.
• Torne os campos privados; exponha construtores e acessadores. Preserve invariantes.
• Use newtypes para IDs e unidades. struct UserId(u64) previne trocas de argumentos.
• Derive Debug, Clone, Eq quando a semântica corresponder. Documente quando não derivar.
• Evite campos Vec públicos, a menos que sejam verdadeiramente irrestritos. Exponha iteradores ou métodos.

B - Design de Enums

• Substitua pares de booleanos por enums quando os estados se multiplicarem. enum Phase é melhor que is_started + is_done.
• Coloque dados apenas em variantes que precisam deles. Ready vs Running { token }.
• Use #[non_exhaustive] em enums públicos extensíveis. Evolução compatível com versões futuras.
• Transicione via métodos que consomem self. Transições ilegais se tornam erros de tipo ou Result.
• Use Box em cargas úteis grandes de variantes. Mantenha o tamanho do enum razoável.

C - Pattern Matching

• Mantenha os braços do match pequenos; extraia helpers. Funções de transição legíveis.
• Prefira if let para fluxos de padrão único. Reduza o ruído em comparação com match de um braço.
• Use let else para padrões necessários. Retorno antecipado em formato inesperado.
• Evite unwrap em enums de domínio em código de biblioteca. Retorne Result com contexto.
• Teste cada variante em caminhos críticos. A adição de variantes deve falhar nos testes até ser atualizada.

D - Serialização e APIs

• Separe DTOs de rede dos tipos de domínio quando as formas diferirem. Valide na fronteira.
• Use atributos serde em enums para JSON com tag. #[serde(tag = "type")] etc.
• Documente a semântica das variantes em rustdoc. Consumidores também fazem correspondência externamente.
• Versionar discriminantes de enum persistidos. Plano de migração ao reordenar variantes.
• Não exponha enums internos em APIs públicas sem uma história de estabilidade. Implicações de Semver.

FAQs

Relacionados

• Noções Básicas de Structs
• Enums para Máquinas de Estado
• Noções Básicas de Traits
• Boas Práticas de Tratamento de Erros

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+.