Regras de Tratamento de Erros

Bibliotecas expõem erros tipados e acionáveis; aplicativos agregam contexto e reportam para usuários e logs. Panics são para bugs, não falhas esperadas.

Receita

// biblioteca
#[derive(thiserror::Error, Debug)]
pub enum Error {
    #[error("não encontrado: {0}")]
    NotFound(UserId),
}
 
// aplicativo
fn main() -> anyhow::Result<()> {
    run().context("inicialização do app")?;
    Ok(())
}

Quando usar isso: Qualquer limite de API pública e binário main.

Exemplo Funcional

pub fn load_config() -> Result<Config, ConfigError> { /* ... */ }
 
async fn handler() -> Result<Json<User>, ApiError> {
    let user = repo.get(id).await?;
    Ok(Json(user))
}

O que isso demonstra:

• ? propaga no mesmo tipo de erro ou com impl From
• Bibliotecas nunca usam unwrap em caminhos de entrada do usuário
• Aplicativos adicionam .context("durante X") nos limites
• Cadeia source() preservada para logs

Mergulho Profundo

• Use #[non_exhaustive] em enums de erro públicos para flexibilidade de semver
• anyhow apenas em binários/testes de integração, não na API pública de bibliotecas publicadas
• Error::source para encadeamento; evite erros apenas de string em bibliotecas

Armadilhas

• Erros de string em biblioteca - correspondência sem tipo. Correção: variantes de enum.
• anyhow em fn pública de biblioteca - apaga tipos para os chamadores. Correção: Result<T, Error> concreto.
• panic para validação - UX ruim. Correção: 400 com mensagem.
• map_err perde a origem - .map_err(|e| e.to_string()) cego. Correção: #[from] ou variantes transparentes.
• ignorar erros com let _ - falhas silenciosas. Correção: logar ou propagar.

Alternativas

FAQs

Relacionado

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

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