Melhores Práticas de Tratamento de Erros

Estratégia de erro consistente entre bibliotecas vs. aplicações.

As equipes Go enviam mais rápido quando cada pacote concorda sobre como os erros são criados, encapsulados, inspecionados, registrados e expostos aos clientes.

Estas regras transformam os artigos sobre tratamento de erros nesta seção em hábitos revisáveis para bibliotecas, serviços e CLIs.

Como Usar Esta Lista

• Aplique durante o design de API, implementação de manipuladores e revisão de código para qualquer função que retorne error.
• Bibliotecas e aplicações têm trabalhos diferentes: retornar vs. traduzir.
• Releia ao integrar novos membros ou quando um serviço adiciona gRPC ao lado de HTTP.

A - Disciplina Central

• Verifique imediatamente cada retorno de error. Erros ignorados são bugs; use linters (errcheck) em CI.
• Retorne (zero, err) em caso de falha; nunca use o valor de sucesso quando err != nil. Os chamadores dependem desse invariante.
• Use errors.Is e errors.As em vez de == e correspondência de strings. Sobrevive a cadeias de encapsulamento e mudanças de texto.
• Encapsule com fmt.Errorf("operação: %w", err) para adicionar contexto. Um encapsulamento por camada com nomes de operação significativos.
• Retorne nil error em caso de sucesso, não ponteiros nil tipados. Evita surpresas com err != nil em caminhos de sucesso.

B - Biblioteca vs. Aplicação

• Bibliotecas retornam erros; elas não registram e retornam o mesmo erro. Evite ruído de log duplicado, a menos que adicione contexto único indisponível a montante.
• Aplicações mapeiam erros para status HTTP/gRPC em manipuladores ou interceptadores. Pacotes de domínio permanecem agnósticos ao transporte.
• Exponha apenas contratos de sentinel e tipos estáveis. Erros não exportados liberam você para refatorar internos.
• Não entre em pânico por falhas esperadas de validação ou I/O em bibliotecas. Retorne error para que os chamadores controlem o comportamento de saída.
• Use %v em vez de %w em limites públicos quando as causas internas devem permanecer ocultas. Troca de segurança e abstração.

C - Contratos de API e Cliente

• Exponha códigos estáveis e legíveis por máquina (tipo problem, código gRPC), não texto bruto de Error(). Clientes ramificam em códigos.
• Mapeie context.DeadlineExceeded para respostas de timeout (504/408, gRPC deadline exceeded). Dinstinga timeouts de "não encontrado".
• Registre causas de 5xx com ID da requisição; retorne mensagens opacas aos clientes. Inclua stacks apenas no lado do servidor.
• Documente quais erros são retentáveis. Política opcional Retryable() bool ou código gRPC documentado.
• Mantenha erros de validação agregados com errors.Join quando todos os campos importam. Resposta única listando cada falha.

D - Concorrência e Operações

• Nunca escreva variáveis err compartilhadas de goroutines sem sincronização. Use canais ou errgroup.
• Cancele trabalhos irmãos na primeira falha com errgroup.WithContext. Economiza cotas e CPU.
• Propague context.Context e encapsule ctx.Err() com %w. Chamadores distinguem cancelamento de falha de I/O.
• Capture debug.Stack em diagnósticos de aplicação, não em bibliotecas reutilizáveis. Stacks são para operadores.
• Teste caminhos de erro: errors.Is, errors.As e status HTTP/gRPC mapeados. Testes apenas de caminhos de sucesso perdem regressões.

E - Estilo e Manutenção

• Nomeie sentinels ErrX em PascalCase. Corresponde às convenções da biblioteca padrão.
• Prefira poucos sentinels; use tipos customizados quando campos são necessários. Evite hierarquias estilo exceção.
• Mantenha strings de Error() concisas e estáveis em significado. A lógica do programa usa campos e Is/As, não substrings.
• Revise novas dependências externas quanto ao comportamento de encapsulamento de erros. ORMs e SDKs podem precisar de mapeadores adaptadores.
• Alinhe o ADR da equipe para 400 vs 422 para validação e mantenha-o. Políticas mistas quebram SDKs de cliente.

FAQs

Relacionado

• Erros como Valores: A Filosofia de Erro do Go - fundação conceitual
• Noções Básicas de Tratamento de Erros - introdução à seção executável
• Erros Sentinel e errors.Is - regras de sentinel em profundidade
• Encapsulamento de Erros com %w e errors.As - mecânica de encapsulamento
• Design de Erros de API para Serviços HTTP e gRPC - contratos de cliente

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).