Documentação de Go
Handlers HTTP e middleware em Go
Referência sobre http.Handler, http.HandlerFunc, composição de handlers e a ordem de execução dos middleware em net/http.
Revisado em 2026-11-16
O contrato http.Handler
A interface http.Handler possui o método ServeHTTP(http.ResponseWriter, *http.Request). Um valor que implementa esse método pode receber uma requisição e produzir uma resposta. O servidor, o ServeMux e middleware podem ser conectados por esse contrato.
A interface torna possível envolver o mux sem depender do tipo concreto das rotas registradas nele.
type Handler interface {
ServeHTTP(ResponseWriter, *Request)
}Adaptar uma função com http.HandlerFunc
http.HandlerFunc é um tipo de função com um método ServeHTTP. Converter uma função com a assinatura HTTP compatível para esse tipo permite usar uma função como um valor http.Handler.
A função anônima de um middleware pode capturar o handler seguinte numa closure. A variável continua disponível quando o handler externo for chamado pelo servidor.
func logging(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
log.Printf("%s %s", r.Method, r.URL.Path)
next.ServeHTTP(w, r)
})
}Compor e ordenar middleware
Um middleware recebe o próximo http.Handler e devolve outro handler. A chamada next.ServeHTTP encaminha a mesma requisição e resposta para a próxima peça. Sem essa chamada, o fluxo não chega ao handler interno.
A ordem de composição determina a ordem de entrada e retorno. Se logging(auth(mux)) for montado de dentro para fora, logging executa primeiro na entrada; depois auth; por fim mux. Quando a chamada interna retorna, o código após next executa na ordem inversa.
Middleware HTTP costuma pertencer à plataforma ou ao bootstrap. Regras de negócio continuam em domínio e aplicação, sem depender de net/http.
handler := logging(mux)
server := &http.Server{Handler: handler}Middleware não depende de uma arquitetura específica
O contrato http.Handler pertence à biblioteca HTTP de Go. Uma aplicação em camadas, MVC, hexagonal ou sem um estilo arquitetural nomeado pode compor handlers da mesma maneira, desde que o ponto de entrada use net/http.
O lugar que conecta o middleware depende da organização do programa. Pode ser o bootstrap, a montagem do router ou a inicialização do servidor. Essa escolha não muda o funcionamento da cadeia. O exemplo hexagonal usa bootstrap porque ali o mux e os handlers dos módulos são reunidos.
Mantenha a dependência no limite HTTP: o middleware pode chamar os contratos HTTP, enquanto domínio e casos de uso não precisam importar net/http.
Limites de um logger simples
Registrar método e caminho não captura status, duração nem panic. Para observar status é preciso envolver http.ResponseWriter com cuidado, inclusive respeitando interfaces opcionais usadas pelo servidor. Recuperar panic também pede uma decisão explícita de como responder e registrar a falha.
Evite incluir tokens, credenciais ou corpos de requisição em logs sem uma necessidade e uma política de proteção claras.