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.

## Fontes primárias

-   [Go net/http — Handler](https://pkg.go.dev/net/http#Handler)
-   [Go net/http — HandlerFunc](https://pkg.go.dev/net/http#HandlerFunc)
-   [Go net/http — ServeMux](https://pkg.go.dev/net/http#ServeMux)
-   [Go Specification — Function literals](https://go.dev/ref/spec#Function_literals)
-   [Go net/http — Request](https://pkg.go.dev/net/http#Request)

## Relacionado

-   [Tutorial básico de middleware em Go](/learning/middleware-em-go-basico)
-   [Interfaces em Go](/reference/go/interfaces)
-   [Ponteiros e endereços em Go](/reference/go/pointers)
