O Go adota uma visão relativamente diferente dos erros em comparação com linguagens como Java, C++ e JavaScript e Python: no Go, o erro é um valor do tipo integrado error, e a função normalmente o retorna ao chamador junto com os demais valores de retorno. Assim, a verificação e o tratamento de erros tornam-se uma parte explícita do fluxo do programa, em vez de serem transferidos para um mecanismo separado de exceções.
O guia da JetBrains, originalmente escrito pelo colaborador da comunidade Christoph Berger e posteriormente transferido para o blog JetBrains Go, apresenta um conjunto de técnicas e práticas para lidar com erros de entrada e saída, rede, validação de dados, entre outros. Ele foi atualizado em agosto de 2026 para acompanhar as mudanças mais recentes da linguagem Go.
O retorno é o ponto de partida
Quando a função não tem contexto suficiente para tratar o problema, ela deve retornar o erro à função chamadora. O Go geralmente coloca o valor de erro no fim da lista de retornos; uma função como ReadFile() retorna o conteúdo do arquivo e um erro cujo valor é nil em caso de sucesso ou diferente de nil em caso de falha.
O guia explica que o chamador deve testar o erro imediatamente, em vez de ignorá-lo. Se a função tiver aberto um recurso, como um arquivo ou uma conexão de rede, deve usar defer para limpá-lo ao sair, mas somente depois de confirmar que a abertura foi bem-sucedida, pois tentar fechar um recurso inválido pode causar um problema adicional.
Adicionar contexto sem danificar a estrutura do erro
O erro pode passar por uma cadeia de funções antes de ser tratado ou registrado. Durante essa passagem, cada função pode adicionar informações úteis, como a operação que falhou ou o caminho que estava sendo processado. No entanto, converter o erro em texto por meio da concatenação de err.Error() faz com que a cadeia e a estrutura tipada do erro sejam perdidas.
A abordagem correta é usar fmt.Errorf() com o verbo %w para encapsular o erro, preservando o erro original. Isso permite usar posteriormente errors.Unwrap() para acessar uma camada, ou errors.Is() e errors.As() para testar erros específicos dentro da cadeia de encapsulamento. O Go 1.26 adiciona a função genérica errors.AsType() como uma alternativa com segurança de tipos a As(); ela retorna o erro correspondente e um valor booleano, permitindo que o compilador detecte erros de tipo que poderiam surgir em tempo de execução com a abordagem mais antiga.
Múltiplos erros e contexto cancelado
Os erros nem sempre formam uma cadeia linear. Ao processar um conjunto de arquivos, por exemplo, algumas operações podem ter sucesso e outras podem falhar. O pacote padrão oferece errors.Join(), disponível desde o Go 1.20, para reunir vários erros em um único valor, preservando o conteúdo processado com sucesso.
O guia alerta que errors.Unwrap() retorna um único valor e, por isso, retorna nil ao lidar com um erro combinado. Para acessar os erros reunidos, é preciso verificar se o valor implementa a interface que fornece Unwrap() []error. Desde o Go 1.20, também é possível usar context.WithCancelCause() para associar um motivo personalizado ao cancelamento do contexto e, em seguida, recuperar esse motivo por meio de context.Cause(ctx), em vez de se limitar ao valor genérico context.Canceled.
Quando panic é apropriado?
panic e recover não devem substituir habitualmente a verificação de erros. Erros esperados, como entradas inválidas do usuário, arquivos ausentes ou tempos limite de rede, devem ser tratados e retornados pelo fluxo de retorno normal.
O panic torna-se apropriado quando o problema é inesperado e não existe um tratamento significativo para ele, como a falha ao compilar uma expressão regular constante cuja validade deveria ter sido verificada previamente. Em servidores HTTP, o aplicativo pode usar recover() dentro de uma função adiada para impedir que o colapso do processamento da solicitação atual afete outras solicitações, quando isso for possível. Já situações como o esgotamento da memória podem não deixar ao aplicativo uma opção prática de continuar.
O que é importante na prática para os desenvolvedores?
- Não ignore os erros: atribuir o valor do erro ao identificador em branco ou descartar o único valor de retorno pode atrasar a descoberta do problema e tornar mais difícil diagnosticar seus efeitos posteriores.
- Registre no local adequado: a função deve tratar o erro ou retorná-lo ao chamador. O guia recomenda que as bibliotecas evitem registrar automaticamente, pois seus usuários podem preferir registros ou destinos de saída diferentes.
- Use tipos apropriados: tipos de erro personalizados podem conter informações adicionais, assim como fs.PathError, que fornece a operação, o caminho e o erro interno.
- Diferencie erros de rede: net.OpError permite examinar a natureza da falha de conexão, e um erro temporário pode permitir uma nova tentativa ou o uso de uma estratégia como o recuo exponencial.
- Aproveite a contagem de bytes nas operações de entrada e saída: a interface io.Reader retorna o número de bytes processados junto com o erro, o que pode ajudar a retomar a operação em vez de repetir todos os dados.
- Preste atenção a io.EOF: esse valor indica o fim bem-sucedido de um fluxo de leitura segundo a semântica do pacote e não representa necessariamente uma falha que precise ser registrada como um erro comum.
- Não use log.Fatal() sem considerar as consequências: ele chama os.Exit(), fazendo com que as funções adiadas sejam ignoradas; por isso, o guia sugere limitar seu uso ou usar os.Exit() na função main().
A conclusão editorial da certi.news é que a clareza do fluxo de erros faz parte do projeto do programa, e não é apenas um estilo de escrita prolixo. O encapsulamento organizado, os tipos apropriados e o registro responsável tornam o diagnóstico executável, enquanto a dependência de panic, de mensagens genéricas ou do descarte de erros oculta as informações de que o desenvolvedor precisará posteriormente. A decisão prática continua relacionada ao contexto do aplicativo: um servidor de solicitações pode precisar de uma recuperação limitada, enquanto um erro irrecuperável pode exigir o encerramento e a reinicialização.