net/http: A Pilha HTTP Completa do Go
O Go envia um servidor e cliente HTTP completos na biblioteca padrão.
//
Busque em todas as páginas da documentação
O Go envia um servidor e cliente HTTP completos na biblioteca padrão.
Você pode construir APIs, proxies e ferramentas CLI que chamam serviços remotos sem importar um framework web.
Noções Básicas de net/http coleta snippets executáveis; artigos irmãos cobrem roteamento, clientes, middleware, HTTP/2, testes e configuração de produção.
net/http implementa servidores e clientes HTTP/1.1 e HTTP/2 com roteamento (ServeMux), interfaces de handler, pooling de conexões, TLS e utilitários para testes e proxy.HTTP em Go gira em torno de uma interface:
type Handler interface {
ServeHTTP(ResponseWriter, *Request)
}Qualquer coisa que possa responder a uma requisição HTTP implementa ServeHTTP.
http.HandlerFunc adapta funções simples, então a maioria dos handlers são closures ou pequenas structs.
No lado do servidor, http.Server é o proprietário do listener, configuração TLS e campos de timeout.
http.ListenAndServe é um wrapper de conveniência que cria um Server padrão e bloqueia até que o processo seja encerrado ou o listener falhe.
O roteamento passa por http.ServeMux, que mapeia padrões de host, método e caminho para handlers.
Go 1.22 expandiu a correspondência de padrões para que rotas como GET /users/{id} e POST /items/ sejam de primeira classe sem um roteador de terceiros.
No lado do cliente, http.Client envia requisições.
Cada cliente possui um http.Transport que gerencia conexões TCP, handshakes TLS, keep-alives e upgrade para HTTP/2 quando habilitado.
O http.DefaultClient padrão não tem timeout de requisição e reutiliza um transporte compartilhado - bom para scripts rápidos, arriscado em servidores.
Middleware não é uma palavra-chave da biblioteca padrão.
É o padrão de envolver um http.Handler com outro: logging, autenticação, recuperação de pânico e IDs de requisição compõem-se como wrappers aninhados em torno do seu handler de negócios.
Uma requisição entra pelo listener, é analisada em *http.Request, correspondida pelo mux e despachada para o handler mais interno.
O handler escreve em http.ResponseWriter; cabeçalhos e status devem ser definidos antes que o corpo seja transmitido.
r.Context() carrega o cancelamento quando o cliente se desconecta ou os timeouts do servidor expiram.
O código downstream deve passar esse contexto para chamadas de banco de dados e RPC.
Cliente Servidor net/http
| |
|------ TCP / TLS ------------>|
| | ReadHeaderTimeout
| | correspondência do ServeMux
| | cadeia de middleware
| | Handler.ServeHTTP
|<----- resposta --------------|
Chamadas de saída espelham o caminho em ordem inversa: Client.Do seleciona ou disca uma conexão do pool, escreve a requisição, lê a resposta e retorna o corpo (que o chamador deve fechar).
| Componente | Papel do Servidor | Papel do Cliente |
|---|---|---|
ServeMux | Roteia para o handler | N/A |
http.Server | Timeouts, TLS, desligamento | N/A |
http.Client | N/A | Envia requisições, respeita o contexto |
Transport | N/A | Agrupa conexões, HTTP/2 |
httputil.ReverseProxy | Encaminha para upstream | N/A |
Frameworks como chi, gin e echo ainda se baseiam em handlers net/http.
Eles adicionam roteamento mais rico, binding e registros de middleware, mas exportam pontos de entrada compatíveis com http.Handler.
Serviços de produção definem timeouts explícitos do servidor: ReadHeaderTimeout, ReadTimeout, WriteTimeout e IdleTimeout protegem cada um um modo de falha diferente.
Ataques Slowloris, uploads travados e vazamentos de conexão ociosa são problemas da biblioteca padrão que você resolve com campos em http.Server, não com mágica de framework.
HTTP/2 é habilitado por padrão para listeners TLS em lançamentos recentes do Go.
HTTP/2 em texto claro (h2c) requer configuração explícita quando você termina TLS em um balanceador de carga e fala h2c internamente.
httputil.ReverseProxy implementa padrões de gateway e BFF: reescreve caminhos, injeta cabeçalhos e transmite corpos sem bufferizar payloads inteiros.
Combine-o com http.Transport ajustado para keep-alives upstream.
Hooks de observabilidade se conectam nas fronteiras do middleware: envolva ResponseWriter para capturar códigos de status, propague IDs de rastreamento de cabeçalhos para o context e emita métricas por padrão de caminho.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
net/http Bruto | Dependências mínimas, controle total | Mais boilerplate para roteamento/recursos | Pequenas APIs, proxies, sidecars |
| chi / roteadores mux | Compatível com biblioteca padrão, leve | Ainda sem validação/ORM | Serviços REST que desejam rotas melhores |
| gin / echo | DX rápido, helpers de binding | Opiniões mais pesadas | Equipes que desejam recursos prontos |
| gRPC + grpc-gateway | Contratos fortes | Não é nativo HTTP | Malhas de serviço, RPC interno |
ListenAndServe está pronto para produção fora da caixa - Funciona para demonstrações, mas a falta de timeouts, TLS e desligamento gracioso causará problemas sob tráfego real.func(http.Handler) http.Handler; frameworks apenas coletam e ordenam wrappers.http.Get é bom dentro de handlers - http.DefaultClient não tem timeout e compartilha estado global; use um http.Client dedicado por dependência.{id} sem gorilla/mux.A biblioteca padrão fornece servidor, cliente, TLS, HTTP/2, auxiliares de teste e utilitários de proxy reverso em um único caminho de importação.
Não inclui validação, templating além de auxiliares básicos ou scaffolding de projeto.
Use chi, gin ou echo quando quiser rotas agrupadas, binding de parâmetros ou um grande ecossistema de middleware pronto para uso.
Fique com net/http bruto quando a contagem de dependências e o controle explícito importarem mais do que atalhos de DX.
Cada *http.Request carrega Context() que cancela em limites de desconexão do cliente e de timeout do servidor.
Handlers devem passá-lo para todas as chamadas bloqueantes downstream.
http.DefaultServeMux é um singleton global.
Prefira um http.NewServeMux() dedicado por serviço para que testes e bibliotecas não registrem rotas conflitantes.
Sim, para listeners TLS com negociação ALPN.
h2c em texto claro requer configuração explícita de Server e Transport.
Handler é uma interface com ServeHTTP.
HandlerFunc é um tipo de função que implementa Handler, permitindo que você escreva handlers func(w, r) sem uma struct.
Sim.
Termine o TLS no ingress ou pod, defina ReadHeaderTimeout e use Shutdown para implantações contínuas.
httptest.ResponseRecorder captura respostas na memória.
httptest.NewServer inicia um listener real para testes do tipo integração.
O pooling http.DefaultTransport é compartilhado e seus padrões podem não corresponder às suas necessidades de latência ou TLS.
Um Transport dedicado por dependência de saída isola o ajuste e os timeouts.
Sim, quando os handlers evitam alocações por requisição, reutilizam clientes e definem limites de conexão ociosa.
Faça o perfil antes de assumir que um framework é mais rápido - muitas vezes o gargalo é a lógica da aplicação, não a biblioteca padrão.
A conexão é abortada, a menos que o middleware de recuperação capture o pânico e retorne 500.
Sempre adicione recuperação na camada de middleware mais externa em produção.
Chame server.Shutdown(ctx) para parar de aceitar novas conexões e aguardar as requisições em andamento.
Combine com o tratamento de sinais em main e um contexto de desligamento limitado.
Versões da Pilha: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (mais recente - verifique na compilação), gin (mais recente - verifique na compilação), echo (mais recente - verifique na compilação), google.golang.org/grpc (mais recente - verifique na compilação), sigs.k8s.io/controller-runtime (mais recente - verifique na compilação), kubebuilder (mais recente - verifique na compilação), tinygo (mais recente - verifique os alvos de placa na compilação), wazero (mais recente - verifique na compilação) e golangci-lint (mais recente - verifique o conjunto de linters na compilação).
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026