gorilla/mux: Rotas Regex e Correspondência de Host

gorilla/mux é um roteador maduro para net/http que enfatiza restrições explícitas de rota: variáveis de caminho regex, roteamento baseado em host, cabeçalhos, consultas e esquemas.

Ele se destaca quando os URLs carregam formatos rigorosos (IDs com prefixos, segmentos de versão, subdomínios de locatário) que a correspondência de segmento no estilo chi expressa de forma desajeitada.

Resumo

mux compila rotas em uma lista de correspondentes avaliada por solicitação.

Cada rota pode exigir métodos HTTP, nomes de host, cabeçalhos e chaves de consulta, além de modelos de caminho.

Os handlers permanecem compatíveis com a stdlib, mas o projeto está em modo de manutenção - escolha mux quando seus correspondentes resolverem um problema real de roteamento, não por padrão para novos serviços.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

r := mux.NewRouter()
r.Host("{tenant}.example.com").
    Path("/api/v{version:[0-9]+}/items/{id:[a-z]+}").
    Methods(http.MethodGet).
    HandlerFunc(getItem)

Quando usar isso:

• Aplicativos multilocatário roteando por subdomínio ({tenant}.api.example.com)
• Caminhos que exigem validação regex no roteador (id deve corresponder a [0-9]{6})
• Correspondência de cabeçalhos (Accept, cabeçalhos de autenticação personalizados) ou presença de consulta
• Bases de código legadas já padronizadas em mux

Exemplo de Trabalho

package 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)
}

O que isso demonstra:

• Modelo de host capturando o slug do locatário
• Segmento de versão restrito a dígitos via regex
• ID do item restrito a letras minúsculas com comprimento mínimo
• mux.Vars mapeia capturas nomeadas para a lógica do handler

Mergulho Profundo

Como Funciona

• NewRouter cria um roteador raiz que implementa http.Handler.
• As rotas registram correspondentes; a primeira rota totalmente correspondente vence (a ordem importa quando os padrões se sobrepõem).
• Subrouter() escopa prefixos de caminho e herda os correspondentes do pai.
• StrictSlash controla o comportamento da barra final via r.StrictSlash(true).

Blocos de Construção de Correspondentes

Regex em Variáveis de Caminho

Use a sintaxe {nome:padrão}.

{id:[0-9]+} rejeita IDs não numéricos antes que seu handler seja executado, retornando 404 para não correspondências.

Mantenha os regex legíveis - padrões complexos pertencem à documentação e aos testes.

Notas Go

// Middleware com mux: envolva o roteador ou handlers por rota
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 não distribui um pacote de middleware rico como chi; componha wrappers no estilo stdlib ou use alice se você quiser helpers de encadeamento.

Armadilhas

• Modo de manutenção - gorilla/mux recebe correções, mas poucos recursos; projetos greenfield de longo prazo geralmente escolhem chi, a menos que os correspondentes sejam obrigatórios. Correção: documente o requisito do correspondente em ADRs ao escolher mux.
• Ordem e sobreposição de rotas - Rotas mais amplas registradas antes das específicas podem mascarar o tráfego. Correção: registre as rotas mais específicas primeiro ou use sub-roteadores para isolar domínios.
• Custo e legibilidade do Regex - Regex pesado em caminhos quentes é mais difícil de depurar do que a validação do handler. Correção: restrinja apenas o que o roteamento deve rejeitar antecipadamente; valide regras de negócios em handlers.
• Correspondência de host atrás de proxies - r.Host pode refletir nomes internos, a menos que Forwarded/X-Forwarded-Host seja normalizado. Correção: termine o TLS no gateway que define o host externo, ou o middleware reescreve r.Host deliberadamente.
• Vars ausentes na rota errada - mux.Vars retorna nil se os nomes dos correspondentes diferirem das expectativas do handler. Correção: teste unitariamente cada modelo e centralize helpers de análise de vars.
• Surpresas com StrictSlash - Redirecionamentos automáticos podem confundir clientes de API que não seguem 301/308. Correção: alinhe os URLs do cliente com a política StrictSlash.

Alternativas

FAQs

Relacionado

• chi: Roteamento Leve e Middleware - escolha de roteador padrão para muitas equipes
• Frameworks HTTP Go: Roteadores vs Frameworks Completos - cenário de roteador vs framework
• Guia de Decisão de Seleção de Framework - quando mux se classifica mais alto
• Migrando Entre Roteadores Sem Reescrever Handlers - portabilidade de handler stdlib
• Servidores HTTP, Handlers e Padrões ServeMux - linha de base de roteamento stdlib

Versões da Stack: Esta página foi escrita para Go 1.26.x (Padrão GC Green Tea, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).