Relatório de Erros

Apresente erros acionáveis para usuários de CLI com anyhow e miette.

Receita

use anyhow::Context;
 
fn read_config(path: &str) -> anyhow::Result<String> {
    std::fs::read_to_string(path)
        .with_context(|| format!("falha ao ler a configuração em {path}"))
}
 
fn main() -> anyhow::Result<()> {
    let cfg = read_config("app.toml")?;
    println!("carregado {cfg}");
    Ok(())
}

Quando usar isso: Binários de aplicação onde os usuários precisam de mensagens ricas em contexto, não erros tipados no estilo de biblioteca.

Exemplo Funcional

use miette::{miette, IntoDiagnostic, Result};
 
#[derive(Debug, thiserror::Error, Diagnostic)]
#[error("porta inválida: {0}")]
#[diagnostic(code(app::invalid_port))]
struct InvalidPort(u16);
 
fn parse_port(s: &str) -> Result<u16> {
    let port: u16 = s.parse().into_diagnostic()?;
    if port == 0 {
        return Err(miette!(InvalidPort(port)));
    }
    Ok(port)
}
 
fn main() -> Result<()> {
    let port = parse_port("0")?;
    println!("escutando em {port}");
    Ok(())
}

O que isso demonstra:

• anyhow::Context adiciona contexto de localização a erros std
• miette fornece códigos de diagnóstico e relatórios formatados
• thiserror define tipos de erro de domínio pequenos
• main retorna Result para saída não zero automática

Análise Detalhada

anyhow vs thiserror vs miette

Diretrizes de Erro de CLI

• Um problema por mensagem de erro
• Diga o que falhou, por quê e como corrigir
• Imprima em stderr; nunca misture erros em stdout JSON
• Encadeie contexto ao cruzar limites de subsistema

Códigos de Saída

use std::process::ExitCode;
 
fn main() -> ExitCode {
    if let Err(e) = run() {
        eprintln!("{e:#}");
        return ExitCode::FAILURE;
    }
    ExitCode::SUCCESS
}

Use {:#} para a cadeia completa do anyhow.

Armadilhas

• Imprimir apenas Display - Usuários perdem a cadeia de erros. Correção: Use {:#} ou miette::Report.
• Panics em CLI - Stack traces feias para usuários. Correção: Retorne Result e reserve panics para bugs.
• Bibliotecas usam anyhow - Chamadores não podem comparar tipos de erro. Correção: Bibliotecas usam thiserror; binários envolvem com anyhow.
• RUST_BACKTRACE verboso por padrão - Sobrecarrega usuários. Correção: Mostre backtrace apenas com --verbose ou dica de ambiente.
• Vazamento de caminhos internos - /home/ci/... confunde usuários. Correção: Remova ou relativize caminhos em mensagens de usuário.

Alternativas

FAQs

Relacionado

• Noções Básicas de CLI - códigos de saída
• clap - erros de validação
• Configuração e Ambiente - falhas de carregamento de configuração
• Melhores Práticas de CLI - mensagens acionáveis

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