gorilla/mux: Rutas Regex y Coincidencia de Host
gorilla/mux es un enrutador maduro de net/http que enfatiza restricciones de ruta explícitas: variables de ruta regex, enrutamiento basado en host, encabezados, consultas y esquemas.
//
Busca en todas las páginas de la documentación
gorilla/mux es un enrutador maduro de net/http que enfatiza restricciones de ruta explícitas: variables de ruta regex, enrutamiento basado en host, encabezados, consultas y esquemas.
Brilla cuando las URL tienen formatos estrictos (IDs con prefijos, segmentos de versión, subdominios de inquilino) que el emparejamiento de segmentos al estilo chi expresa torpemente.
mux compila rutas en una lista de correspondencias evaluada por solicitud.
Cada ruta puede requerir métodos HTTP, nombres de host, encabezados y claves de consulta además de plantillas de ruta.
Los manejadores siguen siendo compatibles con la biblioteca estándar, pero el proyecto está en modo de mantenimiento: elija mux cuando sus correspondencias resuelvan un problema de enrutamiento real, no por defecto para nuevos servicios.
Tarjeta de receta de referencia rápida, lista para copiar y pegar.
r := mux.NewRouter()
r.Host("{tenant}.example.com").
Path("/api/v{version:[0-9]+}/items/{id:[a-z]+}").
Methods(http.MethodGet).
HandlerFunc(getItem)Cuándo usar esto:
{tenant}.api.example.com)id debe coincidir con [0-9]{6})Accept, encabezados de autenticación personalizados) o presencia de consultapackage main
import (
"encoding/json"
"net/http"
"strconv"
"github.com/gorilla/mux"
)
type item struct {
ID string `json:"id"`
Version int `json:"version"`
Tenant string `json:"tenant"`
}
func getItem(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
out := item{
ID: vars["id"],
Version: mustAtoi(vars["version"]),
Tenant: vars["tenant"],
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(out)
}
func mustAtoi(s string) int {
n, _ := strconv.Atoi(s)
return n
}
func main() {
r := mux.NewRouter()
api := r.Host("{tenant:[a-z0-9-]+}.localhost").Subrouter()
api.HandleFunc("/v{version:[0-9]+}/items/{id:[a-z]{3,}}", getItem).Methods(http.MethodGet)
r.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("ok"))
})
http.ListenAndServe(":8080", r)
}Lo que esto demuestra:
mux.Vars mapea las capturas nombradas a la lógica del manejadorNewRouter crea un enrutador raíz que implementa http.Handler.Subrouter() delimita prefijos de ruta y hereda las correspondencias del padre.StrictSlash controla el comportamiento de la barra final mediante r.StrictSlash(true).| Constructor | Propósito | Ejemplo |
|---|---|---|
Path / PathPrefix | Plantilla de ruta | /users/{id} |
Host | Subdominio o dominio | {tenant}.example.com |
Methods | Lista de permitidos de verbos | GET, POST |
Headers | Valores de encabezado requeridos | X-API-Key presente |
Queries | Reglas de clave/valor de consulta | format=json |
Schemes | http vs https | Enrutamiento terminado en TLS |
Use la sintaxis {nombre:patrón}.
{id:[0-9]+} rechaza IDs no numéricos antes de que se ejecute su manejador, devolviendo 404 para las no coincidencias.
Mantenga las expresiones regulares legibles; los patrones complejos pertenecen a la documentación y las pruebas.
// Middleware con mux: envuelve el enrutador o los manejadores por ruta
func logging(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
slog.Info("request", "path", r.URL.Path, "host", r.Host)
next.ServeHTTP(w, r)
})
}
srv := &http.Server{Addr: ":8080", Handler: logging(r)}mux no proporciona un paquete de middleware enriquecido como chi; componga envoltorios al estilo de la biblioteca estándar o use alice si desea ayudantes de encadenamiento.
r.Host puede reflejar nombres internos a menos que Forwarded/X-Forwarded-Host se normalice. Solución: termine TLS en una puerta de enlace que establezca el host externo, o el middleware reescriba r.Host deliberadamente.mux.Vars devuelve nil si los nombres de las correspondencias difieren de las expectativas del manejador. Solución: pruebe unitariamente cada plantilla y centralice las funciones auxiliares de análisis de variables.StrictSlash.| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| chi | Enrutamiento radix moderno, ecosistema de middleware activo | Necesita correspondencias de host/regex que mux proporciona limpiamente |
ServeMux de la biblioteca estándar | Patrones simples {id} en Go 1.22+ | Las reglas de host/encabezado/consulta son complejas |
| Gin/Echo | Vinculación de framework y ayudantes JSON | Quiere manejadores de biblioteca estándar y correspondencias explícitas |
| Pasarela API (nginx, Envoy) | Enrutamiento de host/ruta en el borde | Solo necesita enrutamiento en proceso |
Está en modo de mantenimiento: seguro para aplicaciones existentes, pero evalúe chi o el enrutamiento de borde para nuevos servicios a menos que se requieran las correspondencias de mux.
Ambos nombran segmentos; mux agrega restricciones regex en línea y correspondencias adicionales para host, encabezados y consultas en el mismo constructor de rutas.
Sí: envuelva el enrutador o los manejadores individuales utilizando middleware estándar func(http.Handler) http.Handler.
Use httptest con rutas completamente calificadas y encabezados Host establecidos en la solicitud para ejercitar las correspondencias de host.
mux devuelve 404; use r.NotFoundHandler para personalizar respuestas y registros.
Los subenrutadores hijos combinan prefijos de ruta del padre y pueden agregar sus propias restricciones de Host o Headers.
Use mux para la forma estructural de la URL (IDs solo de dígitos); mantenga la validación de negocio (existe en la base de datos) en manejadores/servicios.
No incorporado: agregue middleware que establezca encabezados Access-Control-* antes de sus manejadores.
Reescriba las plantillas de ruta ({id:regex} a {id} o validación del manejador) y reemplace mux.Vars con chi.URLParam; mantenga los manejadores si ya tienen forma de biblioteca estándar.
Sí: las correspondencias de host en rutas o subenrutadores distribuyen por r.Host en un oyente compartido.
Configure TLS del servidor http.Server como de costumbre; use Schemes("https") cuando termine TLS en proceso.
Las pasarelas de borde se destacan en TLS y enrutamiento grueso; las reglas de host en proceso ayudan cuando desea un binario y un enrutamiento comprobable sin infraestructura adicional.
Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado GC 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 el conjunto de linters en la compilación).
Revisado por Chris St. John·Última actualización: 16 jul 2026