Boas Práticas do net/http

Serviços HTTP sem framework que escalam e encerram de forma limpa.

Aplique estas regras em revisões de código, modelos de serviço e testes de carga para que toda a superfície HTTP da biblioteca padrão se comporte de forma previsível sob tráfego de produção.

Como Usar Esta Lista

• Marque as regras à medida que seu modelo de serviço as adota.
• Codifique os itens da Classe A em bots de revisão de CI ou testes de unidade de arquitetura, onde possível.
• Emparelhe as regras de timeout com tabelas de SLO documentadas por dependência upstream.
• Revise ao adicionar gateways, WebSockets ou novas APIs de saída.

A - Servidor e roteamento

• Construa http.NewServeMux() em main, não http.DefaultServeMux. Previne colisões de rotas no lado da importação entre pacotes.
• Defina ReadHeaderTimeout em todo http.Server de produção. Bloqueia stalls de cabeçalho estilo slowloris antes que os manipuladores sejam executados.
• Configure IdleTimeout para recuperar conexões keep-alive. Para vazamentos de descritores em clientes inativos.
• Use padrões de método e caminho do Go 1.22+ para rotas REST. Mantém a correspondência de método declarativa e testável.
• Limite corpos POST com http.MaxBytesReader. Rejeita payloads excessivos antes do trabalho de decodificação JSON.

B - Ciclo de vida gracioso

• Manipule SIGINT/SIGTERM e chame server.Shutdown(ctx). Implantações em rolo drenam o trabalho em andamento em vez de forçar o encerramento.
• Vincule o contexto de shutdown ao período de graça do orquestrador. Evita ficar pendurado após o terminationGracePeriodSeconds do Kubernetes.
• Pare de aceitar novo trabalho antes de fechar dependências. Desligue primeiro o listener HTTP, depois os pools de banco de dados e clientes.
• Exponha um /health barato sem middleware de autenticação. Balanceadores de carga precisam de um sinal de liveness rápido.
• Documente rotas de streaming isentas de WriteTimeout. SSE e long polls precisam de exceções explícitas de timeout.

C - Manipuladores e contexto

• Passe r.Context() como o primeiro argumento para todas as chamadas downstream bloqueantes. Honra desconexões do cliente e prazos do servidor.
• Retorne silenciosamente em context.Canceled quando a resposta não puder ser enviada. Evita 500s enganosos após o cliente ter saído.
• Defina Content-Type antes de escrever corpos JSON. Previne respostas ambíguas e clientes quebrados.
• Chame WriteHeader uma vez; use http.Error para falhas. O primeiro Write trava o status em 200 se os cabeçalhos não foram enviados.
• Feche ou leia completamente r.Body em todos os caminhos. Necessário para reutilização de conexão keep-alive no lado do servidor.

D - Middleware

• Coloque a recuperação de pânico mais externamente na cadeia de middleware. Pânicos internos se tornam respostas 500 sem saída do processo.
• Autentique antes dos manipuladores de negócios, mas após a recuperação/log. Falha na autenticação interrompe sem tocar na lógica de domínio.
• Envolva ResponseWriter para capturar o status para métricas e logs de acesso. O escritor padrão oculta o status final do middleware.
• Armazene metadados de requisição no contexto com tipos não exportados. Evita colisões de chaves de string entre bibliotecas.
• Permita caminhos de health e métricas no middleware de autenticação. Sondas não precisam de credenciais de serviço.

E - Clientes de saída

• Injete um http.Client por dependência upstream. Isola timeouts e ajuste de transporte por SLA.
• Nunca chame http.Get de manipuladores. http.DefaultClient não tem timeout e é global para o processo.
• Sempre defer resp.Body.Close() após client.Do. Corpos vazados esgotam pools de conexão.
• Drene corpos de resposta de erro antes de fechar ao reutilizar keep-alive. io.Copy(io.Discard, resp.Body) em caminhos não 2xx.
• Defina MaxIdleConnsPerHost para upstreams quentes. Reduz o churn de TLS e TCP sob QPS constante.

F - Proxies, TLS e HTTP/2

• Defina Transport personalizado em httputil.ReverseProxy. O transporte padrão é compartilhado e não ajustado para caminhos de gateway.
• Implemente ErrorHandler em proxies reversos. Mapeia timeouts de dial e cabeçalho para 502/504 consistentemente.
• Defina tls.Config.MinVersion para TLS 1.2 ou superior. Documenta a postura de cifra aceitável para listeners externos.
• Saiba se os pods falam HTTP/2, h2c ou HTTP/1.1 atrás do ingress. Configuração incorreta aparece como bugs latentes de multiplexação.
• Confie em X-Forwarded-* apenas de balanceadores de carga conhecidos. Previne metadados de IP e esquema falsificados pelo cliente.

FAQs

Relacionado

• net/http: A Pilha HTTP Incluída nas Baterias do Go - âncora conceitual
• Noções Básicas de net/http - exemplos iniciais executáveis
• Lista de Verificação de Configuração de net/http de Produção - verificação pré-implantação
• HTTP/2, Timeouts e ReverseProxy - profundidade de timeout e proxy
• Cadeias de Middleware e Contexto de Requisição - ordenação de middleware

Versões de 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 (ú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).