chi: Roteamento Leve e Middleware

O chi adiciona roteamento ciente de métodos, parâmetros de URL e composição de middleware sobre o net/http sem introduzir um tipo de handler personalizado.

Handlers continuam sendo func(http.ResponseWriter, *http.Request), então o chi se encaixa em equipes que desejam a ergonomia de um roteador com portabilidade do stdlib.

Resumo

O chi constrói uma árvore de radix de rotas no momento do registro e despacha as requisições recebidas através de uma pilha de middleware antes que seu handler seja executado.

Grupos de rotas (Route, Group, Mount) permitem que você escopo middleware e prefixos para subárvores.

Como chi.Router implementa http.Handler, você o insere em http.Server, testes de integração e proxies reversos da mesma forma que faria com um ServeMux simples.

Receita

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

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)

Quando usar isso:

• APIs REST que precisam de rotas agrupadas e middleware sem dependência de framework
• Serviços que devem compor com middleware http.Handler do stdlib (OTel, gateways de autenticação)
• Bibliotecas que expõem um http.Handler para os consumidores montarem
• Migração incremental do http.ServeMux mantendo os handlers existentes

Exemplo de Trabalho

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

O que isso demonstra:

• Pilha de middleware aplicada a todas as rotas /api/v1
• Análise de parâmetro de URL com validação antes da consulta ao domínio
• Leitura/escrita de JSON sem um wrapper de contexto de framework
• Timeouts voltados para produção e recuperação de pânico do middleware chi

Mergulho Profundo

Como Funciona

• chi.NewRouter() aloca uma árvore de rotas; cada Get/Post registra um nó de método + padrão.
• Use envolve a cadeia de handlers do roteador atual; sub-roteadores herdam o middleware pai, a menos que sejam registrados antes de um branch.
• Mount("/prefix", sub) remove o prefixo e delega a correspondência para sub.
• Requisições não correspondentes caem para http.NotFound, a menos que você defina r.NotFound e r.MethodNotAllowed.

Padrões de Rota em Resumo

Ordem do Middleware

O middleware externo é executado primeiro na entrada e por último na saída.

Registre logging e recuperação cedo; coloque a autenticação após o logging para que as requisições rejeitadas ainda deixem um rastro de auditoria.

O middleware de timeout deve ficar fora dos handlers que podem bloquear.

Notas de Go

import "context"
 
// Middleware personalizado: anexa um valor ao 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))
    })
}

Prefira chaves de contexto tipadas (tipo int personalizado) em vez de strings nuas para evitar colisões.

Armadilhas

• Remoção de prefixo do Mount - Handlers em roteadores montados veem caminhos sem o prefixo de montagem; registrar o r.URL.Path bruto confunde os operadores. Correção: registre chi.RouteContext(r).RoutePattern ou inclua o prefixo de montagem em campos estruturados.
• Middleware no roteador errado - Chamar Use após Mount não envolve retroativamente subárvores montadas registradas anteriormente. Correção: registre Use compartilhado no pai antes de Mount, ou adicione middleware em cada sub-roteador.
• Parâmetro sempre string - chi.URLParam retorna string; esquecer strconv produz IDs 0 silenciosos. Correção: analise e valide antes das chamadas de domínio.
• Timeouts padrão do servidor - http.ListenAndServe usa timeouts zero; o middleware Timeout do chi ajuda, mas não substitui ReadHeaderTimeout em http.Server. Correção: configure os timeouts de http.Server explicitamente.
• Redirecionamentos de barra final - O chi pode redirecionar /users para /users/ dependendo do registro; clientes inconsistentes podem dar requisições duplas. Correção: escolha um estilo e registre ambos ou desative os redirecionamentos conscientemente.
• Estado global em handlers - Exemplos usam mapas por brevidade; código de produção precisa de stores injetados. Correção: feche dependências através de construtores de handler que retornam http.HandlerFunc.

Alternativas

FAQs

Relacionados

• Noções Básicas de Frameworks Web - rotas e grupos de hello do chi
• Frameworks HTTP Go: Roteadores vs Frameworks Completos - posicionamento do roteador
• gorilla/mux: Rotas Regex e Correspondência de Host - quando os padrões do mux vencem
• Middleware e Padrões Decorator - composição de middleware
• Cadeias de Middleware e Contexto de Requisição - contexto em middleware

Versões de 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).