Padrões de Middleware & Decorator

Middleware em Go envolve um http.Handler com outro http.Handler para adicionar comportamento transversal: logging, autenticação, recuperação e métricas.

É a forma prática do padrão decorator em uma linguagem sem herança.

Resumo

Cada middleware recebe o próximo handler, retorna um novo handler e decide se executa a lógica antes, depois ou em torno da chamada interna.

O servidor net/http invoca o handler mais externo; o middleware aninha para dentro até que o handler da rota seja executado.

O mesmo modelo de composição aparece em chi, gin, echo e interceptores gRPC com helpers de registro específicos do framework.

Receita

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

func logging(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        next.ServeHTTP(w, r)
        slog.Info("handled", "path", r.URL.Path, "ms", time.Since(start).Milliseconds())
    })
}

Quando usar isso:

• Preocupações transversais compartilhadas entre muitas rotas
• Autenticação/autorização, IDs de requisição, recuperação de pânico, propagação de tracing
• Envolvimento de resposta (capturando código de status e bytes escritos)

Exemplo de Trabalho

package main
 
import (
    "context"
    "log"
    "net/http"
    "time"
 
    "github.com/go-chi/chi/v5"
    "github.com/go-chi/chi/v5/middleware"
)
 
type ctxKey int
 
const userKey ctxKey = 1
 
func withUser(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        token := r.Header.Get("Authorization")
        if token == "" {
            http.Error(w, "unauthorized", http.StatusUnauthorized)
            return
        }
        ctx := context.WithValue(r.Context(), userKey, "demo-user")
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}
 
func greet(w http.ResponseWriter, r *http.Request) {
    user, _ := r.Context().Value(userKey).(string)
    w.Write([]byte("hello " + user))
}
 
func main() {
    r := chi.NewRouter()
    r.Use(middleware.RequestID)
    r.Use(middleware.Recoverer)
    r.Use(withUser)
    r.Get("/greet", greet)
 
    srv := &http.Server{
        Addr:         ":8080",
        Handler:      r,
        ReadTimeout:  5 * time.Second,
        WriteTimeout: 10 * time.Second,
    }
    log.Fatal(srv.ListenAndServe())
}

O que isso demonstra:

• r.Use registra middleware para rotas registradas nesse roteador
• O middleware de autenticação encerra a requisição com http.Error antes de chamar next
• O ID do usuário no escopo da requisição flui através de context.Context
• O middleware chi compõe com handlers da biblioteca padrão

Mergulho Profundo

Como Funciona

Request -->
  Middleware RequestID
    --> Middleware Recoverer
      --> Middleware withUser
        --> Handler greet
      <-- withUser (após next retornar)
    <-- Recoverer
  <-- RequestID
Response <--

• Entrada: de fora para dentro; saída: de dentro para fora (como camadas de cebola)
• O middleware deve chamar next.ServeHTTP a menos que ele lide completamente com a requisição
• Envolver ResponseWriter captura o status e o tamanho do corpo para métricas

Envolvimento de ResponseWriter

type statusWriter struct {
    http.ResponseWriter
    code int
}
 
func (w *statusWriter) WriteHeader(code int) {
    w.code = code
    w.ResponseWriter.WriteHeader(code)
}

• Embutir http.ResponseWriter para delegar a maioria dos métodos
• Sobrescrever WriteHeader e Write para observar o comportamento
• Usar http.ResponseController (Go 1.20+) para flush/hijack quando necessário

Notas de Framework

Notas de Go

• Prefira chaves de contexto tipadas não exportadas em vez de chaves de string para evitar colisões
• Não armazene objetos grandes no contexto - passe IDs e carregue nos handlers
• Mantenha o middleware livre de banco de dados e regras de negócios além de autenticação/logging

Armadilhas

• Esquecer de chamar next - Requisição fica pendente ou retorna resposta vazia. Correção: sempre chame next.ServeHTTP a menos que você tenha escrito a resposta completa.
• Chaves de contexto de string - Colidem com outros middlewares usando "user". Correção: constantes de chave tipada privada por pacote.
• Lógica de negócios em middleware - Difícil de testar; fluxo de controle oculto. Correção: middleware define o contexto; handlers e serviços decidem os resultados.
• Múltiplos wrappers de ResponseWriter - Interfaces Flusher/Hijacker perdidas se o wrapper não as implementar. Correção: use middleware.NewWrapResponseWriter do chi ou implemente interfaces opcionais.
• Bugs na ordem do middleware - Autenticação após um handler que entra em pânico ignora a recuperação. Correção: registre Recoverer como o mais externo; autenticação antes de handlers que precisam de identidade.
• Estado global em middleware - Limitadores de taxa no nível do pacote ocultam dependências. Correção: feche as dependências ao construir middleware em main.

Alternativas

FAQs

Relacionados

• Básico de Padrões Go - exemplo de cadeia de middleware
• Padrões de Camada de Repositório e Serviço - handlers delegam para serviços
• Idiomas Go: Composição Sobre Herança - modelo de composição de função
• Funções Construtoras e APIs de Pacote - conectando middleware em main

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 na compilação).