Boas Práticas de Tratamento de Erros

Como Usar Esta Lista

• Bibliotecas: erros tipados. Aplicações: anyhow/eyre ricos em contexto.
• Revise antes de adicionar unwrap a caminhos de produção.

A - Bibliotecas

• Use thiserror para enums de erro públicos. Variantes estáveis e comparáveis.
• Implemente Error + Display + From para fontes. Habilita cadeias com ?.
• Evite anyhow em APIs públicas. Consumidores precisam de erros tipados.
• Marque enums extensíveis com #[non_exhaustive]. Evolução amigável a Semver.
• Documente quais variantes são transitórias vs. permanentes. Lógica de retentativa depende disso.

B - Aplicações

• Use anyhow ou eyre na fronteira do binário. Anexe contexto liberalmente.
• Retorne códigos de saída diferentes de zero de CLIs. Mapeie Err para o código 1+.
• Registre a cadeia completa de erros uma vez na fronteira. Evite camadas de contexto duplicadas.
• Mapeie erros para status HTTP apenas nos manipuladores. Mantenha erros de domínio agnósticos ao transporte.
• Habilite backtraces em falhas de CI de staging. RUST_BACKTRACE=1.

C - Panics e unwrap

• Sem unwrap em caminhos falíveis de bibliotecas. Retorne Result.
• Use expect com mensagem apenas quando o invariante for documentado. Testes e lógica provável.
• Prefira ? a boilerplate de match. Caminho feliz mais claro.
• Use debug_assert! para invariantes de desenvolvimento. Não validações de usuário.
• Nunca cause panic através de FFI. Retorne códigos de erro.

D - Options e Results

• Option para opcional, Result para falha. Não confunda.
• Use combinadores antes de aninhamento profundo de match. Legibilidade.
• Colete iteradores Result com consciência de interrupção. Documente a política de falha parcial.
• Adicione contexto nas fronteiras das operações. Caminhos de arquivo, IDs de usuário, IDs de solicitação.
• Teste caminhos de erro, não apenas Ok. Inclua testes de entrada inválida.

FAQs

Relacionados

• Noções Básicas de Tratamento de Erros
• thiserror
• anyhow
• Estratégia de Erros

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