Hasta la versión 1.21, el http.ServeMux de la librería estándar era extremadamente básico. Solo permitía realizar un matching basado en prefijos (si la ruta terminaba en /) o coincidencias exactas. Si querías construir una API RESTful moderna, tenías dos opciones: implementar una lógica manual tediosa dentro de tus handlers para verificar el método HTTP (if r.Method != "GET" ...) o meterte en el ecosistema de librerías externas como gorilla/mux o chi.
A partir de Go 1.22, el ServeMux fue rediseñado para incluir un sistema de routing mucho más potente que cubre el 90% de los casos de uso en microservicios, sin necesidad de dependencias externas. Ahora, el multiplexer no solo mira el path, sino que incluye el método HTTP en el patrón de coincidencia y soporta parámetros de ruta mediante comodines.
El funcionamiento se basa en un sistema de precedencia determinista: el router busca el patrón más específico que coincida con la URL y el método. Esto elimina la ambigüedad que solía causar problemas en routers más complejos. Si intentas acceder a una ruta con un método no definido para ese patrón (por ejemplo, un POST a una ruta definida solo para GET), el servidor ahora responde automáticamente con un 405 Method Not Allowed en lugar de un 404 Not Found, un comportamiento mucho más correcto según el protocolo HTTP.
Sin embargo, si no comprendes la jerarquía de los patrones, puedes terminar “tapando” (shadowing) rutas específicas con rutas más genéricas, o confundir un parámetro de ruta con un comodín de captura total.
package main
import (
"fmt"
"net/http"
)
func main() {
// Creamos un nuevo multiplexer.
// Con Go 1.22+, este ya soporta patrones avanzados.
mux := http.NewServeMux()
// 1. Routing basado en método y parámetros de ruta {id}
// Solo responderá a peticiones GET. Si haces un POST, devolverá 405.
mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
// Extraemos el parámetro usando PathValue
id := r.PathValue("id")
fmt.Fprintf(w, "Obteniendo datos del usuario con ID: %s\n", id)
})
// 2. Otro parámetro de ruta para un endpoint de creación
mux.HandleFunc("POST /users", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprint(w, "Usuario creado con éxito\n")
})
// 3. Wildcard (comodín) para rutas de archivos o sub-recursos
// El sufijo "..." captura todo lo que siga después de /files/
mux.HandleFunc("GET /files/{path...}", func(w http.ResponseWriter, r *http.Request) {
path := r.PathValue("path")
fmt.Fprintf(w, "Accediendo al archivo en la ruta: %s\n", path)
})
// 4. Precedencia: La ruta exacta tiene prioridad sobre la de parámetro
mux.HandleFunc("GET /users/admin", func(w *http.ResponseWriter, r *http.Request) {
fmt.Fprint(w, "Acceso al panel de administración\n")
})
// Servidor en el puerto 8080
fmt.Println("Servidor escuchando en :8080...")
if err := http.ListenAndServe(":8080", mux); err != nil {
panic(err)
}
}
Análisis del código
Fíjate en cómo la declaración mux.HandleFunc("GET /users/{id}", ...) encapsula dos responsabilidades que antes eran manuales: la validación del método y el parsing del path.
En la función del usuario, r.PathValue("id") es la forma estándar de recuperar el valor capturado en el segmento {id}. No necesitas hacer splits manuales de la URL ni expresiones regulares. El runtime de Go hace este trabajo de forma eficiente durante el proceso de matching.
Un punto crítico es la precedencia. Si llamamos a /users/admin, el router comparará este path con /users/{id} y /users/admin. Al ser /users/admin una coincidencia exacta y más específica, el router elegirá este handler sin importar el orden en que se hayan registrado los handlers. Esto es fundamental para evitar que una ruta parametrizada “devore” a una ruta estática.
Finalmente, el uso de {path...} es el wildcard. A diferencia de {id}, que solo captura un segmento de la URL (hasta la siguiente /), el comodín con puntos suspensivos captura todo el resto de la ruta, lo cual es ideal para implementaciones de servidores de archivos estáticos o proxies.
El error frecuente
Un error común al migrar de routers antiguos o al empezar con el nuevo ServeMux es la confusión entre parámetros de segmento y comodines de captura total.
Si defines una ruta como /api/{resource}, y el cliente llama a /api/v1/config, el router no coincidirá porque {resource} espera un único segmento. En este caso, el router lanzará un 404 Not Found. Para que el router acepte múltiples segmentos después de /api/, debes usar obligatoriamente el comodín: /api/{resource...}.
Otro error es intentar usar r.PathValue para obtener un parámetro en una ruta que no fue definida explícitamente con un nombre de variable en el patrón. El valor será una cadena vacía, lo cual puede pasar desapercibido y causar errores de lógica de negocio en producción.
N° 190