Melhores Práticas para Depuração e Cenários de Defeitos

Checklists de prevenção e modelos de RCA para incidentes em Go.

Estas regras transformam arestas cortantes recorrentes em hábitos de revisão, portões de CI e notas pós-incidente que impedem que a mesma classe de defeito seja enviada duas vezes.

Como Usar Esta Lista

• Percorra as seções A-D durante a revisão de código para manipuladores concorrentes, parsers e camadas de repositório.
• Habilite go test -race, govet e golangci-lint em pacotes que compartilham estado mutável.
• Em incidentes, classifique os sintomas usando a taxonomia do explicador antes de reescrever a lógica de negócios.
• Armazene os resultados do RCA como ADRs ou habilitações de linter, não apenas em threads do Slack.

A - Triagem e Observabilidade

• Classifique primeiro a família de sintomas (nil, slice, race, leak, time). Combine pilhas e métricas com um bucket de defeito antes de alterações profundas no código.
• Capture pilhas de pânico completas e contagens de goroutines no início do incidente. GOTRACEBACK=all e endpoints pprof aceleram a causa raiz.
• Registre IDs de requisição, metadados RPC e timestamps RFC3339 em erros. Correlacione relatórios de usuários com rastros de requisição únicos.
• Reproduza sob -race e paralelismo realista. Passes locais instáveis escondem data races que a carga de produção expõe.
• Diferencie interrupções de dependência de defeitos de linguagem. DNS, DB e 5xx de terceiros imitam bugs de aplicação até que os limites sejam verificados.

B - Nil, interfaces e erros

• Nunca retorne (nil, nil) para "não encontrado" em tipos ponteiro. Retorne ErrNotFound ou um sentinel tipado que os chamadores tratam com errors.Is.
• Verifique ponteiros após erros de nil quando APIs permitem valores ausentes. err == nil não garante *T não nulo.
• Evite ponteiros nil tipados em interfaces error. Retorne um erro nil não tipado ou um valor de erro concreto, não (*MyError)(nil), a menos que os chamadores esperem isso.
• Valide ponteiros decodificados de JSON antes do uso. null desserializa para nil sem erro.
• Habilite análise estática de nil (nilaway, staticcheck) em limites de serviço. Capture caminhos de retorno que os analisadores sinalizam antes do pânico em tempo de execução.

C - Slices, mapas e compartilhamento de memória

• Copie ou limite o tamanho antes de passar sub-slices para chamadores. Use s[low:high:high] ou append([]T(nil), s...) quando os consumidores puderem adicionar.
• Registre len, cap e mutações de backing ao depurar bugs de append. Corrupção silenciosa raramente causa pânico.
• Não compartilhe mapas entre goroutines sem sincronização. Use mutex, sync.Map ou locks de shard para caches.
• Trate visualizações de bytes.Buffer.Bytes() como efêmeras. Copie se reter além da próxima mutação do buffer.
• Execute -race quando slices ou structs são mutados a partir de manipuladores e loops de atualização em segundo plano.

D - Concorrência, contexto e loops

• Passe r.Context() através de manipuladores HTTP para todas as I/Os bloqueantes. Desconexão do cliente e Shutdown devem parar o trabalho.
• Sempre chame cancel() de WithCancel/WithTimeout. Use defer cancel() imediatamente após a criação.
• Adicione select em ctx.Done() para goroutines bloqueadas em canais. Evite vazamentos quando os produtores nunca enviam.
• Copie variáveis de loop em goroutines em bibliotecas que visam Go mais antigo. v := v ou passagem de parâmetro continua defensiva após Go 1.22.
• Evite defer dentro de loops sem uma função por iteração. Defers se empilham até a saída da função e vazam descritores de arquivo.
• Use sync.Once para singletons preguiçosos, não inicialização de dupla verificação não sincronizada. O detector de race valida caminhos Once de forma barata.

E - Tempo, desligamento e higiene de produção

• Analise timestamps com zonas explícitas ou ParseInLocation. Layouts sem zona usam UTC, não a zona do laptop do desenvolvedor.
• Armazene instantes em UTC; converta com In(loc) para exibição. Compare com Equal, não com strings formatadas.
• Incorpore time/tzdata ou instale tzdata em contêineres mínimos. LoadLocation falha silenciosamente em CI se nunca for chamado.
• Limite o desligamento gracioso com o timeout de http.Server.Shutdown. Cancele o contexto raiz quando o sinal chegar.
• Documente os campos do modelo RCA: família de sintomas, primeiro frame ruim, guarda ausente, teste de correção permanente. Feche incidentes com um teste de regressão ou regra de linter.

FAQs

Relacionado

• Depuração em Go: Falhas Observáveis e Arestas Cortantes - taxonomia de sintomas
• Noções Básicas de Depuração em Go - ponto de entrada de ferramentas
• Walkthrough de Defeito de Interface Nil vs Ponteiro Nil - regras de nil em profundidade
• Cenários de Data Race e Correções do Detector de Race - correções de race
• Vazamentos de Goroutine e Cancelamento de Contexto Ausente - desligamento e vazamentos
• Staticcheck e golangci-lint em CI - automatizar guardas

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 da 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).

3730363230327c3230356f6967637c6f692e73656469756765646f63