chi: Enrutamiento Ligero y Middleware

chi añade enrutamiento consciente de métodos, parámetros de URL y composición de middleware sobre net/http sin introducir un tipo de manejador personalizado.

Los manejadores siguen siendo func(http.ResponseWriter, *http.Request), por lo que chi se adapta a equipos que desean la ergonomía de un enrutador con portabilidad de stdlib.

Resumen

chi construye un árbol de rutas (radix tree) en tiempo de registro y despacha las solicitudes entrantes a través de una pila de middleware antes de que se ejecute tu manejador.

Los grupos de rutas (Route, Group, Mount) te permiten delimitar middleware y prefijos a subárboles.

Dado que chi.Router implementa http.Handler, puedes insertarlo en http.Server, pruebas de integración y proxies inversos de la misma manera que lo harías con un ServeMux simple.

Receta

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

r := chi.NewRouter()
r.Use(middleware.RequestID, middleware.Recoverer)
 
r.Route("/api", func(r chi.Router) {
    r.Get("/users/{id}", getUser)
})
 
http.ListenAndServe(":8080", r)

Cuándo usar esto:

• APIs REST que necesitan rutas y middleware agrupados sin dependencia de un framework.
• Servicios que deben componerse con middleware http.Handler de stdlib (OTel, pasarelas de autenticación).
• Bibliotecas que exponen un http.Handler para que los consumidores lo monten.
• Migración incremental desde http.ServeMux manteniendo los manejadores existentes.

Ejemplo de Trabajo

package main
 
import (
    "encoding/json"
    "net/http"
    "strconv"
    "time"
 
    "github.com/go-chi/chi/v5"
    "github.com/go-chi/chi/v5/middleware"
)
 
type user struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}
 
var users = map[int]user{1: {ID: 1, Name: "Ada"}}
 
func getUser(w http.ResponseWriter, r *http.Request) {
    id, err := strconv.Atoi(chi.URLParam(r, "id"))
    if err != nil {
        http.Error(w, "invalid id", http.StatusBadRequest)
        return
    }
    u, ok := users[id]
    if !ok {
        http.Error(w, "not found", http.StatusNotFound)
        return
    }
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(u)
}
 
func main() {
    r := chi.NewRouter()
    r.Use(middleware.RequestID)
    r.Use(middleware.RealIP)
    r.Use(middleware.Logger)
    r.Use(middleware.Recoverer)
    r.Use(middleware.Timeout(30 * time.Second))
 
    r.Route("/api/v1", func(r chi.Router) {
        r.Get("/users/{id}", getUser)
        r.Post("/users", func(w http.ResponseWriter, r *http.Request) {
            var in user
            if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
                http.Error(w, err.Error(), http.StatusBadRequest)
                return
            }
            users[in.ID] = in
            w.WriteHeader(http.StatusCreated)
            json.NewEncoder(w).Encode(in)
        })
    })
 
    srv := &http.Server{Addr: ":8080", Handler: r}
    srv.ListenAndServe()
}

Lo que esto demuestra:

• Pila de middleware aplicada a todas las rutas de /api/v1.
• Análisis de parámetros de URL con validación antes de la búsqueda en el dominio.
• Lectura/escritura de JSON sin un envoltorio de contexto del framework.
• Tiempos de espera orientados a producción y recuperación de pánicos del middleware de chi.

Análisis Profundo

Cómo Funciona

• chi.NewRouter() asigna un árbol de rutas; cada Get/Post registra un nodo de método + patrón.
• Use envuelve la cadena de manejadores del enrutador actual; los sub-enrutadores heredan el middleware padre a menos que se registren antes de una rama.
• Mount("/prefix", sub) elimina el prefijo y delega la coincidencia a sub.
• Las solicitudes no coincidentes pasan a http.NotFound a menos que configures r.NotFound y r.MethodNotAllowed.

Patrones de Rutas de un Vistazo

Orden del Middleware

El middleware externo se ejecuta primero al entrar y el último al salir.

Registra el logging y la recuperación temprano; coloca la autenticación después del logging para que las solicitudes rechazadas aún dejen un rastro de auditoría.

El middleware de tiempo de espera debe ubicarse fuera de los manejadores que puedan bloquear.

Notas de Go

import "context"
 
// Middleware personalizado: adjunta un valor al contexto, estilo stdlib
func withTenant(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        tenant := r.Header.Get("X-Tenant")
        type tenantKeyType struct{}
        ctx := context.WithValue(r.Context(), tenantKeyType{}, tenant)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

Prefiere claves de contexto tipadas (tipo entero personalizado) sobre cadenas vacías para evitar colisiones.

Trampas Comunes

• Eliminación de prefijo de Mount - Los manejadores en enrutadores montados ven rutas sin el prefijo de montaje; registrar el r.URL.Path crudo confunde a los operadores. Solución: registra chi.RouteContext(r).RoutePattern o incluye el prefijo de montaje en campos estructurados.
• Middleware en el enrutador incorrecto - Llamar a Use después de Mount no envuelve retroactivamente los subárboles montados registrados anteriormente. Solución: registra Use compartido en el padre antes de Mount, o añade middleware en cada sub-enrutador.
• Parámetro siempre string - chi.URLParam devuelve string; olvidar strconv produce IDs 0 silenciosos. Solución: analiza y valida antes de las llamadas al dominio.
• Tiempos de espera del servidor predeterminados - http.ListenAndServe usa tiempos de espera cero; el middleware Timeout de chi ayuda pero no reemplaza ReadHeaderTimeout en http.Server. Solución: configura explícitamente los tiempos de espera de http.Server.
• Redirecciones de barra final - chi puede redirigir /users a /users/ dependiendo del registro; los clientes inconsistentes pueden golpear dos veces. Solución: elige un estilo y registra ambos o deshabilita las redirecciones conscientemente.
• Estado global en manejadores - Los ejemplos usan mapas por brevedad; el código de producción necesita almacenes inyectados. Solución: cierra las dependencias a través de constructores de manejadores que devuelven http.HandlerFunc.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Frameworks Web - rutas de saludo y grupos de chi
• Frameworks HTTP de Go: Enrutadores vs. Frameworks Completos - posicionamiento del enrutador
• gorilla/mux: Rutas Regex y Coincidencia de Host - cuándo ganan los patrones de mux
• Middleware y Patrones Decorador - composición de middleware
• Cadenas de Middleware y Contexto de Solicitud - contexto en middleware

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado GC de Green Tea, 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).