Controle de Fluxo em Middleware HTTP

Manipuladores HTTP executam concorrentemente sob carga, então um único pânico não deve travar o processo.

Middleware envolve manipuladores com defer/recover, molda o fluxo de controle de escopo de requisição e decide se deve chamar o próximo manipulador - padrões compartilhados entre chi, gin, echo e o stdlib net/http.

Resumo

Envolva cada manipulador de requisição para que um recover diferido registre o pânico e retorne HTTP 500.

Use defer para timers por requisição, fechamento de corpo e spans de rastreamento.

Middleware retorna antecipadamente não chamando next, ou escrevendo uma resposta e retornando.

A recuperação de pânico pertence à camada útil mais externa - geralmente middleware de servidor ou roteador.

Emparelhe a recuperação com logging estruturado e IDs de requisição do contexto.

Receita

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

package main
 
import (
    "log"
    "net/http"
)
 
func recoverMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if rec := recover(); rec != nil {
                log.Printf("panic: %v path=%s", rec, r.URL.Path)
                http.Error(w, http.StatusText(http.StatusInternalServerError),
                    http.StatusInternalServerError)
            }
        }()
        next.ServeHTTP(w, r)
    })
}
 
func hello(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("ok"))
}
 
func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/hello", hello)
    http.ListenAndServe(":8080", recoverMiddleware(mux))
}

Quando usar isso:

• Adicione recuperação de pânico em qualquer servidor HTTP público antes de enviar para produção.
• Use defer para fechar corpos de requisição e encerrar spans de observabilidade por requisição.
• Interrompa middleware de autenticação escrevendo 401 e retornando sem chamar next.
• Empilhe múltiplos middlewares: logging por fora, recuperação mais externa ou apenas dentro do logging, dependendo da pilha de rastreamento desejada.

Exemplo de Trabalho

package main
 
import (
    "context"
    "log"
    "net/http"
    "time"
 
    "github.com/go-chi/chi/v5"
    "github.com/go-chi/chi/v5/middleware"
)
 
func timeoutMiddleware(d time.Duration) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            ctx, cancel := context.WithTimeout(r.Context(), d)
            defer cancel()
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}
 
func main() {
    r := chi.NewRouter()
    r.Use(middleware.RequestID)
    r.Use(middleware.Recoverer) // middleware defer/recover do chi
    r.Use(timeoutMiddleware(2 * time.Second))
 
    r.Get("/boom", func(w http.ResponseWriter, r *http.Request) {
        panic("developer mistake")
    })
 
    r.Get("/ok", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("fine"))
    })
 
    log.Println(http.ListenAndServe(":8080", r))
}

O que isso demonstra:

• O Recoverer do Chi aplica o padrão defer/recover padrão em todas as rotas.
• timeoutMiddleware chama cancel() diferido para liberar recursos do timer quando a requisição termina.
• O contexto flui para os manipuladores via r.WithContext sem globais.
• Pânico em /boom resulta em 500; /ok ainda serve normalmente.

Análise Detalhada

Como Funciona

• Cada requisição executa em sua própria goroutine (ou worker) do net/http; o pânico desfaz apenas essa goroutine.
• Middleware é uma função de ordem superior que envolve http.Handler - o controle passa linearmente, a menos que o middleware retorne antecipadamente.
• defer recover deve estar na mesma função que invoca o manipulador (ou chama next.ServeHTTP).
• Frameworks (gin, echo) expõem middleware Recovery() com pilhas defer semelhantes e rastros de pilha opcionais.
• Camadas duplas de recover são inofensivas, mas redundantes - escolha uma recuperação externa.

Fluxo de Controle de Middleware

Requisição ─► Logging ─► Recover ─► Auth ─► Manipulador
              │          │         │
              │          │         └─ retorna 401 (ignora manipulador)
              │          └─ defer recover em pânico
              └─ defer log latência

Notas sobre Frameworks

Notas sobre Go

// Interrupção de autenticação: não chama next quando não autorizado
func auth(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if r.Header.Get("Authorization") == "" {
            http.Error(w, "unauthorized", http.StatusUnauthorized)
            return
        }
        next.ServeHTTP(w, r)
    })
}

Armadilhas

• Recuperar sem contexto de logging - Pânicos se tornam 500 silenciosos. Correção: registre o ID da requisição, caminho, método e debug.Stack().
• Escrever resposta e depois chamar next - Escritas de resposta duplas causam pânico ou saída corrompida. Correção: retorne imediatamente após escrever a resposta de erro.
• Recuperar apenas dentro do manipulador - Pânicos em middleware externo ainda travam se não forem recuperados. Correção: coloque a recuperação no início da cadeia Use.
• defer body.Close() ausente - r.Body vaza conexões em erros. Correção: defer r.Body.Close() em manipuladores ou middleware compartilhado após o roteamento.
• Usar pânico para erros de validação - Clientes recebem 500 em vez de 4xx. Correção: retorne http.Error com o status apropriado para falhas esperadas.
• Contexto de timeout ignorado downstream - Manipuladores devem aceitar r.Context() em chamadas de I/O, ou os timeouts nunca dispararão. Correção: passe o contexto para http.NewRequestWithContext, chamadas de banco de dados e stubs gRPC.

Alternativas

FAQs

Relacionados

• defer, panic & recover - pilha defer e regras de recover
• Noções Básicas de Controle de Fluxo - exemplo mínimo de recover
• break, continue & Controle de Fluxo Rotulado - interrupção via return em middleware
• Padrões de Servidores, Manipuladores e ServeMux HTTP - fiação do servidor stdlib
• Melhores Práticas de Controle de Fluxo - fluxo de manipulador legível

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão 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).