Patrones de Middleware y Decorador

El middleware en Go envuelve un http.Handler con otro http.Handler para agregar comportamiento transversal: registro, autenticación, recuperación y métricas.

Es la forma práctica del patrón decorador en un lenguaje sin herencia.

Resumen

Cada middleware recibe el siguiente manejador, devuelve un nuevo manejador y decide si ejecutar lógica antes, después o alrededor de la llamada interna.

El servidor net/http invoca el manejador más externo; el middleware se anida hacia adentro hasta que se ejecuta el manejador de ruta.

El mismo modelo de composición aparece en chi, gin, echo e interceptores gRPC con ayudantes de registro específicos del framework.

Receta

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

func logging(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        next.ServeHTTP(w, r)
        slog.Info("handled", "path", r.URL.Path, "ms", time.Since(start).Milliseconds())
    })
}

Cuándo usar esto:

• Preocupaciones transversales compartidas en muchas rutas
• Authn/z, IDs de solicitud, recuperación de pánico, propagación de rastreo
• Envoltura de respuesta (captura de código de estado y bytes escritos)

Ejemplo de Trabajo

package main
 
import (
    "context"
    "log"
    "net/http"
    "time"
 
    "github.com/go-chi/chi/v5"
    "github.com/go-chi/chi/v5/middleware"
)
 
type ctxKey int
 
const userKey ctxKey = 1
 
func withUser(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 greet(w http.ResponseWriter, r *http.Request) {
    user, _ := r.Context().Value(userKey).(string)
    w.Write([]byte("hello " + user))
}
 
func main() {
    r := chi.NewRouter()
    r.Use(middleware.RequestID)
    r.Use(middleware.Recoverer)
    r.Use(withUser)
    r.Get("/greet", greet)
 
    srv := &http.Server{
        Addr:         ":8080",
        Handler:      r,
        ReadTimeout:  5 * time.Second,
        WriteTimeout: 10 * time.Second,
    }
    log.Fatal(srv.ListenAndServe())
}

Lo que esto demuestra:

• r.Use registra middleware para las rutas registradas en ese enrutador
• El middleware de autenticación interrumpe con http.Error antes de llamar a next
• El ID de usuario específico del ámbito de la solicitud fluye a través de context.Context
• El middleware de chi se compone con manejadores de la biblioteca estándar

Inmersión Profunda

Cómo Funciona

Solicitud -->
  Middleware RequestID
    --> Middleware Recoverer
      --> Middleware withUser
        --> manejador greet
      <-- withUser (después de que next retorna)
    <-- Recoverer
  <-- RequestID
Respuesta <--

• Entrada: de externo a interno; salida: de interno a externo (como capas de cebolla)
• El middleware debe llamar a next.ServeHTTP a menos que maneje completamente la solicitud
• Envolver ResponseWriter captura el estado y el tamaño del cuerpo para métricas

Envoltura de ResponseWriter

type statusWriter struct {
    http.ResponseWriter
    code int
}
 
func (w *statusWriter) WriteHeader(code int) {
    w.code = code
    w.ResponseWriter.WriteHeader(code)
}

• Incrustar http.ResponseWriter para delegar la mayoría de los métodos
• Sobrescribir WriteHeader y Write para observar el comportamiento
• Usar http.ResponseController (Go 1.20+) para flush/hijack cuando sea necesario

Notas del Framework

Notas de Go

• Prefiera claves de contexto tipadas no exportadas sobre claves de cadena para evitar colisiones
• No almacene objetos grandes en el contexto: pase IDs y cargue en los manejadores
• Mantenga el middleware libre de reglas de base de datos y de negocio más allá de la autenticación/registro

Trampas

• Olvidar llamar a next: la solicitud se cuelga o devuelve una respuesta vacía. Solución: siempre llame a next.ServeHTTP a menos que haya escrito la respuesta completa.
• Claves de contexto de cadena: colisionan con otros middleware que usan "user". Solución: constantes de clave tipada privada por paquete.
• Lógica de negocio en middleware: difícil de probar; flujo de control oculto. Solución: el middleware establece el contexto; los manejadores y servicios deciden los resultados.
• Múltiples envoltorios de ResponseWriter: las interfaces Flusher/Hijacker se pierden si el envoltorio no las implementa. Solución: use middleware.NewWrapResponseWriter de chi o implemente interfaces opcionales.
• Errores de orden de middleware: la autenticación después de un manejador que entra en pánico omite la recuperación. Solución: registre Recoverer en el exterior; autenticación antes de los manejadores que necesitan identidad.
• Estado global en middleware: los limitadores de velocidad a nivel de paquete ocultan las dependencias. Solución: cierre las dependencias al construir middleware en main.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos básicos de patrones de Go - ejemplo de cadena de middleware
• Patrones de capa de repositorio y servicio - los manejadores delegan a los servicios
• Idiomas de Go: Composición sobre herencia - modelo de composición de funciones
• Funciones constructoras y API de paquetes - cableado de middleware en main

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