Boas Práticas do Pacote context

Convenções de equipe para chaves de context, timeouts e desligamento.

Aplique estas regras em revisões de código, integração e modelos de serviço para que cada handler, repositório e cliente RPC propague o cancelamento de forma consistente.

Como Usar Esta Lista

• Marque as regras à medida que seu modelo de serviço as adota.
• Codifique os itens da Categoria A em verificações personalizadas do golangci-lint ou testes de unidade de arquitetura, sempre que possível.
• Documente os orçamentos de timeout por dependência no README ou na configuração, ao lado da regra.
• Revise trimestralmente ao adicionar clientes RPC ou drivers de banco de dados.

A - Assinaturas de funções e propagação

• Aceite ctx context.Context como o primeiro parâmetro em APIs bloqueantes. Revisores rejeitam novas I/Os sem context.
• Nomeie o parâmetro ctx, não c ou context. Corresponde às expectativas do Effective Go e do staticcheck.
• Passe ctx inalterado, exceto por deadlines ou valores de filhos intencionais. Sem Background() novo no meio da requisição.
• Retorne ctx.Err() quando o cancelamento encerrar o trabalho. Preserve com %w apenas ao adicionar context de camada.
• Substitua Query/Exec por variantes *Context em caminhos de requisição. Proíba SQL sem context em handlers.

B - Pontos de entrada HTTP e RPC

• Contexto do handler raiz em r.Context() ou equivalente de framework. Wrappers chi/gin/echo ainda mapeiam para a requisição.
• Anexe metadados em middleware via r.WithContext. Valores e timeouts curtos envolvem o ctx de entrada.
• Mapeie context.Canceled sem logs 500 barulhentos quando a resposta não puder ser enviada. Registre em debug para abortos de cliente.
• Use http.NewRequestWithContext para HTTP de saída. Vincule o tempo de vida da dependência ao chamador.
• Passe ctx para stubs gRPC e honre deadlines no lado do servidor. Traduza para codes.DeadlineExceeded quando apropriado.

C - Timeouts e deadlines

• Publique uma tabela de timeouts por dependência (DB, cache, auth). Reduza os orçamentos em cada salto a partir do SLO da borda.
• Derive timeouts filhos do pai, nunca de Background(). Preserva o cancelamento do usuário e os relógios upstream.
• Sempre defer cancel() após WithCancel/WithTimeout/WithDeadline. Evita vazamentos de timer em testes e produção.
• Limite as novas tentativas com contextos por tentativa menores. Pare quando o ctx pai já estiver concluído.
• Use Shutdown(ctx) com um context limitado ao sair do processo. Emparelhe com o tratamento de sinais em main.

D - Valores e chaves

• Defina chaves de context como tipos não exportados no pacote proprietário. Evite chaves de string em bibliotecas.
• Limite valores a metadados transversais (ID da requisição, principal, localidade). Filtros de negócios pertencem a structs.
• Exponha acessadores tipados (User(ctx)) em vez de chamadas Value brutas. Mantém os tipos de chave privados.
• Não armazene segredos ou grandes blocos de dados no context. Trate o context apenas como uma preocupação interna do processo.
• Documente as chaves permitidas em um comentário de pacote ou ADR. A integração lê uma lista, não cinquenta arquivos de middleware.

E - Concorrência, testes e operações

• Selecione em ctx.Done() em loops longos e streams. Loops Recv/Send do gRPC verificam cada iteração.
• Use context.WithoutCancel apenas para trabalho pós-resposta documentado. Cobrança e auditoria são casos comuns.
• Teste em tabela os caminhos Canceled e DeadlineExceeded. Timeouts curtos superam time.Sleep em CI.
• Execute -race em pacotes que criam goroutines por requisição. Detecta corridas de cancelamento ignoradas.
• Registre o orçamento de deadline restante nos limites do serviço durante incidentes de debug. Acelera a triagem de latência de cauda.

FAQs

Relacionado

• context.Context: Cancelamento como API de Primeira Classe - âncora conceitual
• Noções Básicas de Contexto - exemplos iniciais executáveis
• Antipadrões de Mau Uso de Contexto - padrões negativos a serem evitados
• Deadlines e Timeouts em Limites de Serviço - exemplos de tabelas de timeout
• Testando Código que Aceita context.Context - verifique os caminhos de cancelamento

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