Clientes HTTP, Transporte e Agrupamento de Conexões

O HTTP de saída em Go flui através de http.Client, que delega o gerenciamento de conexões para http.Transport.

Ajustar timeouts e tamanhos de pool previne vazamentos de goroutine, stalls de TLS e exaustão de conexões sob carga.

Resumo

http.Client é a API de alto nível para enviar requisições.

Seu campo Transport implementa RoundTripper e é responsável pela conexão TCP, TLS, upgrade para HTTP/2 e reutilização de conexões ociosas.

Client.Timeout limita toda a requisição, incluindo a leitura do corpo.

Controle mais fino reside em Transport: DialContext, TLSHandshakeTimeout, ResponseHeaderTimeout e limites de conexão ociosa.

Todo corpo de resposta deve ser fechado para que as conexões retornem ao pool.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

var apiClient = &http.Client{
    Timeout: 10 * time.Second,
    Transport: &http.Transport{
        Proxy:                 http.ProxyFromEnvironment,
        DialContext:           (&net.Dialer{Timeout: 5 * time.Second, KeepAlive: 30 * time.Second}).DialContext,
        TLSHandshakeTimeout:   5 * time.Second,
        ResponseHeaderTimeout: 5 * time.Second,
        MaxIdleConns:          100,
        MaxIdleConnsPerHost:   10,
        IdleConnTimeout:       90 * time.Second,
    },
}
 
req, _ := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
resp, err := apiClient.Do(req)
if err != nil { return err }
defer resp.Body.Close()

Quando usar isso:

• Qualquer serviço que chama APIs HTTP externas a partir de manipuladores ou workers.
• Substituindo http.Get/http.Post em caminhos de código de produção.
• Ajustando keep-alive quando o QPS para um host é alto.

Exemplo de Trabalho

package main
 
import (
    "context"
    "encoding/json"
    "fmt"
    "io"
    "log"
    "net"
    "net/http"
    "time"
)
 
type API struct {
    base   string
    client *http.Client
}
 
func NewAPI(base string) *API {
    return &API{
        base: base,
        client: &http.Client{
            Timeout: 8 * time.Second,
            Transport: &http.Transport{
                DialContext: (&net.Dialer{
                    Timeout:   3 * time.Second,
                    KeepAlive: 30 * time.Second,
                }).DialContext,
                TLSHandshakeTimeout:   3 * time.Second,
                ResponseHeaderTimeout: 4 * time.Second,
                MaxIdleConns:          50,
                MaxIdleConnsPerHost:   8,
                IdleConnTimeout:       60 * time.Second,
            },
        },
    }
}
 
func (a *API) Fetch(ctx context.Context, path string) (map[string]any, error) {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, a.base+path, nil)
    if err != nil {
        return nil, err
    }
    req.Header.Set("Accept", "application/json")
 
    resp, err := a.client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
 
    if resp.StatusCode != http.StatusOK {
        b, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
        return nil, fmt.Errorf("status %d: %s", resp.StatusCode, string(b))
    }
 
    var out map[string]any
    if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
        return nil, err
    }
    return out, nil
}
 
func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
 
    api := NewAPI("https://httpbin.org")
    data, err := api.Fetch(ctx, "/get")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(data["url"])
}

O que isso demonstra:

• http.Client dedicado com ajuste explícito de Transport.
• NewRequestWithContext para propagação de cancelamento.
• defer resp.Body.Close() em todos os caminhos de sucesso e erro.
• Tratamento de status não-2xx com leituras limitadas do corpo de erro.

Mergulho Profundo

Como Funciona

• Client.Do chama Transport.RoundTrip, que disca ou reutiliza uma conexão ociosa.
• Keep-alive retorna conexões TCP para o pool ocioso após Body.Close().
• MaxIdleConnsPerHost limita a reutilização por upstream; conexões excedentes são fechadas após a resposta.
• HTTP/2 multiplexa streams em uma única conexão TLS quando ALPN negocia h2.

Camadas de Timeout

Notas Go

// Injeta rastreamento ou autenticação sem substituir Transport inteiramente:
type roundTripper struct { base http.RoundTripper }
 
func (rt roundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
    req = req.Clone(req.Context())
    req.Header.Set("Authorization", "Bearer "+token)
    return rt.base.RoundTrip(req)
}
 
client.Transport = roundTripper{base: client.Transport}

Parâmetros e Valores de Retorno

Armadilhas

• Usar http.DefaultClient em servidores - Sem timeout e transporte compartilhado em todo o processo. Correção: Construa clientes no nível do pacote ou injetados por dependência.
• Não fechar resp.Body - Vazamentos de conexões até a exaustão do pool. Correção: defer resp.Body.Close() imediatamente após Do bem-sucedido.
• Descartar corpo em status de erro - Conexão não pode ser reutilizada sem drenagem. Correção: io.Copy(io.Discard, resp.Body) antes de fechar em caminhos de erro.
• Definir apenas Client.Timeout - Pode ocultar a necessidade de ResponseHeaderTimeout em servidores lentos. Correção: Camadas de timeouts de transporte para casos de cabeçalho travado.
• Compartilhar um único Cliente com diferentes necessidades de timeout - Todas as chamadas herdam os mesmos limites. Correção: Clientes separados por SLA upstream.
• Mutar http.DefaultTransport - Afeta todo o processo, incluindo bibliotecas. Correção: Clone os padrões em uma nova struct Transport.

Alternativas

FAQs

Relacionados

• Noções Básicas de net/http - exemplo de cliente GET
• Cadeias de Middleware e Contexto de Requisição - propaga ctx para fora
• HTTP/2, Timeouts e ReverseProxy - transporte HTTP/2
• Propagação de Cancelamento em Manipuladores HTTP - ctx de manipuladores
• Lista de Verificação de Configuração de net/http de Produção - itens da lista de verificação do cliente

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