Cadenas de Middleware y Contexto de Solicitud

El middleware envuelve http.Handler para ejecutar lógica transversal antes y después de tus manejadores de ruta.

Los metadatos del ámbito de la solicitud fluyen a través de r.Context() usando claves de contexto tipadas y no exportadas.

Resumen

Una función de middleware acepta un manejador interno y devuelve un nuevo manejador que delega a él.

Las cadenas anidan envoltorios: el middleware más externo ve la solicitud primero y la respuesta última.

r.Context() es el portador estándar para cancelación, plazos y metadatos de solicitud.

Usa r.WithContext para adjuntar valores de forma inmutable; nunca modifiques la solicitud en su lugar sin clonarla.

Bibliotecas como chi proporcionan asistentes Use, pero el modelo subyacente es idéntico a la composición de la biblioteca estándar.

Receta

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

func chain(h http.Handler, mws ...func(http.Handler) http.Handler) http.Handler {
    for i := len(mws) - 1; i >= 0; i-- {
        h = mws[i](h)
    }
    return h
}
 
func requestID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-ID")
        if id == "" {
            id = uuid.NewString()
        }
        ctx := context.WithValue(r.Context(), reqIDKey{}, id)
        w.Header().Set("X-Request-ID", id)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

Cuándo usar esto:

• Agregar registro, autenticación, métricas y recuperación de forma uniforme en todas las rutas.
• Propagar IDs de solicitud e información principal a llamadas posteriores.
• Construir servicios sin framework que aún necesiten preocupaciones transversales.

Ejemplo de Trabajo

package main
 
import (
    "context"
    "log"
    "net/http"
    "time"
)
 
type ctxKey int
 
const userKey ctxKey = 1
 
type statusWriter struct {
    http.ResponseWriter
    code int
}
 
func (w *statusWriter) WriteHeader(code int) {
    w.code = code
    w.ResponseWriter.WriteHeader(code)
}
 
func chain(h http.Handler, mws ...func(http.Handler) http.Handler) http.Handler {
    for i := len(mws) - 1; i >= 0; i-- {
        h = mws[i](h)
    }
    return h
}
 
func recoverer(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if v := recover(); v != nil {
                log.Printf("panic: %v", v)
                http.Error(w, "internal error", http.StatusInternalServerError)
            }
        }()
        next.ServeHTTP(w, r)
    })
}
 
func authenticate(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        token := r.Header.Get("Authorization")
        if token == "" {
            http.Error(w, "unauthorized", http.StatusUnauthorized)
            return
        }
        ctx := context.WithValue(r.Context(), userKey, "demo-user")
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}
 
func accessLog(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        sw := &statusWriter{ResponseWriter: w, code: http.StatusOK}
        start := time.Now()
        next.ServeHTTP(sw, r)
        log.Printf("%s %s %d %s", r.Method, r.URL.Path, sw.code, time.Since(start))
    })
}
 
func userFrom(ctx context.Context) (string, bool) {
    u, ok := ctx.Value(userKey).(string)
    return u, ok
}
 
func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /me", func(w http.ResponseWriter, r *http.Request) {
        user, ok := userFrom(r.Context())
        if !ok {
            http.Error(w, "no user", http.StatusInternalServerError)
            return
        }
        w.Write([]byte(user))
    })
 
    handler := chain(mux, recoverer, authenticate, accessLog)
    http.ListenAndServe(":8080", handler)
}

Lo que esto demuestra:

• Orden explícito de construcción de la cadena de middleware.
• El middleware de autenticación se corta con 401 antes de que se ejecuten los manejadores internos.
• Clave de contexto privada tipada para la identidad del usuario.
• Envoltorio statusWriter que captura el estado HTTP para los registros.
• Recuperación de pánico en la capa más externa.

Inmersión Profunda

Cómo Funciona

• Cada middleware devuelve un nuevo cierre http.Handler sobre el manejador interno.
• El corte (short-circuiting) omite los manejadores internos devolviendo temprano sin llamar a next.ServeHTTP.
• r.WithContext devuelve una copia superficial de la solicitud con un nuevo árbol de contexto.
• El código posterior lee valores con accesores tipados, no con claves de cadena crudas.

Orden del Middleware

Solicitud -->
  recoverer -->
    authenticate -->
      accessLog -->
        mux / manejador de negocio
Respuesta <--

El middleware externo debe incluir recuperación y rastreo; la autenticación se sienta dentro de la recuperación pero fuera de la lógica de negocio.

Notas de Go

// Equivalente en chi (manejadores stdlib debajo):
// r.Use(middleware.Recoverer, middleware.RequestID)
// r.Get("/me", handler)
 
// Prefiere accesores:
func User(ctx context.Context) (string, bool) {
    u, ok := ctx.Value(userKey).(string)
    return u, ok
}

Reglas de Valores de Contexto

Trampas

• Orden incorrecto del middleware - El registro dentro de la autenticación puede filtrar rutas no autenticadas; la recuperación debe ser la más externa. Solución: Documenta el orden: recuperar -> rastrear -> autenticar -> registrar -> rutas.
• Claves de contexto de cadena - Colisionan entre paquetes silenciosamente. Solución: Usa constantes privadas type ctxKey int.
• Almacenar la solicitud en el contexto - Crea referencias circulares y confunde los ciclos de vida. Solución: Almacena solo los pocos valores que los manejadores necesitan.
• Modificar r.URL sin Clonar - Carrera cuando el middleware comparte solicitudes. Solución: Usa r.Clone(ctx) al alterar la URL o las cabeceras para sub-enrutadores.
• Olvidar llamar a next.ServeHTTP - Descarta solicitudes silenciosamente. Solución: Usa linting o prueba el middleware con httptest afirmando que el cuerpo se alcanzó.
• Pasar context.Background() aguas abajo - Pierde la cancelación ante la desconexión del cliente. Solución: Empieza desde r.Context() para todos los contextos hijos.

Alternativas

Preguntas Frecuentes

Relacionado

• Patrones de Servidores, Manejadores y ServeMux HTTP - montar mux envuelto
• Propagación de Cancelación en Manejadores HTTP - propagación de ctx
• Valores de Contexto: Cuándo y Cuándo No - reglas de valores
• Patrones de Middleware y Decorador - patrón general
• Conceptos Básicos de net/http - middleware de registro simple

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