Clientes HTTP, Transporte y Agrupación de Conexiones

El tráfico HTTP saliente en Go fluye a través de http.Client, que delega la gestión de conexiones a http.Transport.

Ajustar los tiempos de espera y los tamaños de los pools evita fugas de goroutines, bloqueos de TLS y agotamiento de conexiones bajo carga.

Resumen

http.Client es la API de alto nivel para enviar solicitudes.

Su campo Transport implementa RoundTripper y es responsable del dial TCP, TLS, la actualización a HTTP/2 y la reutilización de conexiones inactivas.

Client.Timeout limita toda la solicitud, incluida la lectura del cuerpo.

Un control más fino reside en Transport: DialContext, TLSHandshakeTimeout, ResponseHeaderTimeout y los límites de conexiones inactivas.

Cada cuerpo de respuesta debe cerrarse para que las conexiones regresen al pool.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

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

Cuándo usar esto:

• Cualquier servicio que llame a APIs HTTP externas desde manejadores o workers.
• Reemplazar http.Get/http.Post en rutas de código de producción.
• Ajustar keep-alive cuando el QPS a un host es alto.

Ejemplo de Trabajo

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"])
}

Lo que esto demuestra:

• http.Client dedicado con ajuste explícito de Transport.
• NewRequestWithContext para la propagación de cancelación.
• defer resp.Body.Close() en cada ruta de éxito y error.
• Manejo de estados no 2xx con lecturas limitadas del cuerpo de error.

Análisis Profundo

Cómo Funciona

• Client.Do llama a Transport.RoundTrip, que establece una conexión o reutiliza una inactiva.
• Keep-alive devuelve las conexiones TCP al pool inactivo después de Body.Close().
• MaxIdleConnsPerHost limita la reutilización por host de destino; las conexiones excesivas se cierran después de la respuesta.
• HTTP/2 multiplexa flujos en una única conexión TLS cuando ALPN negocia h2.

Capas de Tiempo de Espera

Notas de Go

// Inyectar tracing o autenticación sin reemplazar Transport por completo:
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 y Valores de Retorno

Errores Comunes

• Usar http.DefaultClient en servidores - Sin tiempo de espera y transporte compartido en todo el proceso. Solución: Construir clientes a nivel de paquete o inyectados por dependencia.
• No cerrar resp.Body - Fuga conexiones hasta el agotamiento del pool. Solución: defer resp.Body.Close() inmediatamente después de un Do exitoso.
• Descartar el cuerpo en estado de error - La conexión no se puede reutilizar sin drenarla. Solución: io.Copy(io.Discard, resp.Body) antes de cerrar en rutas de error.
• Establecer solo Client.Timeout - Puede ocultar la necesidad de ResponseHeaderTimeout en servidores lentos. Solución: Superponer tiempos de espera de transporte para casos de cabeceras colgadas.
• Compartir un único Cliente con diferentes necesidades de tiempo de espera - Todas las llamadas heredan los mismos límites. Solución: Clientes separados por SLA de upstream.
• Mutar http.DefaultTransport - Afecta a todo el proceso, incluidas las bibliotecas. Solución: Clonar los valores predeterminados en una nueva estructura Transport.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos básicos de net/http - ejemplo de cliente GET
• Cadenas de Middleware y Contexto de Solicitud - propagar ctx saliente
• HTTP/2, Tiempos de Espera y ReverseProxy - transporte HTTP/2
• Propagación de Cancelación en Manejadores HTTP - ctx desde manejadores
• Lista de Verificación de Configuración de net/http en Producción - elementos de la lista de verificación del cliente

Versiones de Stack: Esta página fue escrita para Go 1.26.x (Valor predeterminado de GC Green Tea, go fix modernizers - verificar parche en build), chi (última - verificar en build), gin (última - verificar en build), echo (última - verificar en build), google.golang.org/grpc (última - verificar en build), sigs.k8s.io/controller-runtime (última - verificar en build), kubebuilder (última - verificar en build), tinygo (última - verificar objetivos de placa en build), wazero (última - verificar en build), y golangci-lint (última - verificar conjunto de linters en build).