thiserror
Tipos de erro personalizados
thiserror é uma aula grátis de Learn Rust Coding no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Learn Rust Coding, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Learn Rust Coding inclui 4 aulas no total.
Por que usar erros personalizados?
As bibliotecas devem expor tipos de erro significativos para que quem as chama possa reagir a falhas específicas. Escrevê-los manualmente exige muito código repetitivo. O pacote thiserror faz isso por você.
Adicionando thiserror
Adicione-o como dependência. Ele é um pacote de macros de derivação sem custo em tempo de execução.
[dependencies]
thiserror = "1.0"Definindo uma enumeração de erros
Derive Error em uma enumeração na qual cada variante represente uma falha distinta. O atributo #[error("...")] fornece a mensagem de Display.
use thiserror::Error;
#[derive(Error, Debug)]
pub enum DataError {
#[error("item not found")]
NotFound,
#[error("invalid input: {0}")]
Invalid(String),
}Interpolando campos
A cadeia de caracteres da mensagem pode referenciar campos nomeados ou posicionais, fazendo com que o texto do erro carregue contexto.
use thiserror::Error;
#[derive(Error, Debug)]
pub enum ConfigError {
#[error("missing key: {key}")]
Missing { key: String },
#[error("value {0} out of range")]
OutOfRange(i32),
}Display e Error automáticos
A derivação implementa automaticamente tanto Display (a partir das suas mensagens) quanto std::error::Error. Não são necessários blocos impl manuais.
Envolvendo um erro de origem
#[from] gera uma implementação de From para que o operador ? possa converter um erro subjacente no seu tipo. #[source] marca a causa.
use thiserror::Error;
#[derive(Error, Debug)]
pub enum AppError {
#[error("io failure")]
Io(#[from] std::io::Error),
#[error("parse failure")]
Parse(#[from] std::num::ParseIntError),
}Usando com ?
Graças a #[from], o operador ? converte automaticamente erros padrão em seu AppError.
fn read_number(path: &str) -> Result<i32, AppError> {
let text = std::fs::read_to_string(path)?; // io::Error -> AppError
let n: i32 = text.trim().parse()?; // ParseIntError -> AppError
Ok(n)
}A cadeia de origem
Quando você envolve um erro, thiserror expõe a causa por meio de Error::source, permitindo cadeias completas de erros para registro e depuração.
Erros transparentes
#[error(transparent)] encaminha tanto Display quanto a origem para o erro envolvido, sendo útil para uma variante de passagem direta.
use thiserror::Error;
#[derive(Error, Debug)]
pub enum WrapError {
#[error(transparent)]
Other(#[from] std::io::Error),
}Quando usar thiserror
Use thiserror quando:
- Você estiver escrevendo uma biblioteca
- Quem chama precisar fazer correspondência com variantes de erro específicas
- Você quiser uma API de erros tipada e estável
Para aplicações nas quais você só quer propagar os erros, anyhow costuma ser mais simples.
Fazendo correspondência em variantes
Como o erro é uma enumeração real, quem chama pode usar match nele para reagir de forma diferente a cada tipo de falha.
fn handle(err: AppError) {
match err {
AppError::Io(_) => println!("retry the file operation"),
AppError::Parse(_) => println!("ask the user to fix input"),
}
}Verificação rápida
O que o atributo #[from] gera em uma enumeração de thiserror?
Recapitulação
Você aprendeu sobre o pacote thiserror:
#[derive(Error)]gera implementações de Display e Error#[error("...")]define mensagens com interpolação de campos#[from]habilita a conversão de erros de origem com?transparentencaminha para um erro envolvido- É ideal para APIs de erros tipados de bibliotecas
Perguntas Frequentes
A aula “thiserror” é grátis?
Sim — o texto completo de “thiserror” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Learn Rust Coding, atualize para CoddyKit PRO. O curso de Learn Rust Coding inclui 4 aulas no total.
O que vou aprender em “thiserror”?
Tipos de erro personalizados Você pratica Learn Rust Coding com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar Learn Rust Coding?
Nenhuma experiência prévia é necessária. Learn Rust Coding no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.
Quanto tempo leva a aula “thiserror”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de Learn Rust Coding?
Sim. Cada aula de Learn Rust Coding inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.