# Entendendo e criando middleware HTTP em Go na prática

Veja como a cadeia de handlers funciona por dentro, implemente um middleware em Go e conecte-o ao router sem acoplar as regras da aplicação ao HTTP.

Nível: Básico em Go e HTTP · Duração: 6 etapas · Linguagem: Go

[Código-fonte do tutorial](https://github.com/bendevjunior/hexagonal-architecture-go)

## Etapa 1: O que é um middleware HTTP?

**Parte:** Conceito

### O que vamos fazer

Visualizar onde uma preocupação compartilhada entra no caminho de uma requisição.

### Por que esta etapa importa

Uma aplicação pode precisar registrar requisições, limitar acesso ou medir duração. Um middleware reúne esse comportamento num ponto da cadeia HTTP e evita que cada endpoint implemente a mesma preocupação por conta própria.

### Onde se encaixa

Middleware é um padrão de composição HTTP, não uma parte exclusiva da arquitetura hexagonal. Em Go, qualquer aplicação que componha valores http.Handler pode envolver seu router ou handler. Neste curso usamos uma aplicação hexagonal como exemplo; em outra arquitetura, o ponto de composição pode estar junto ao router ou à inicialização do servidor.

### Fluxo de execução: Uma cadeia HTTP funciona com qualquer organização interna

**Entrada e chamadas:**

1. **Servidor HTTP:** Recebe a conexão e chama o handler configurado.
2. **Middleware:** Executa sua parte antes da rota e decide se encaminha a requisição.
3. **Router ou handler seguinte:** Seleciona um endpoint ou executa o próximo componente.
4. **Handler da rota:** Trata a requisição e escreve a resposta.

**Retorno do controle:** Handler da rota → Router → Middleware → Servidor HTTP

A organização interna pode ser hexagonal, em camadas, MVC ou mais simples. O middleware depende do contrato HTTP; o sentido das setas mostra a chamada e o retorno do controle.

### Detalhes técnicos e de linguagem

Vamos criar um RequestLogger e depois conectá-lo ao ServeMux. O mesmo padrão serve para outros routers e arquiteturas: o middleware recebe um http.Handler e devolve outro. A organização do domínio muda de projeto para projeto, mas a cadeia HTTP continua tendo um componente externo chamando o próximo.

#### Trechos e conceitos

- `func Middleware(next http.Handler) http.Handler`: O middleware recebe o próximo handler e devolve um handler que o envolve. O valor devolvido pode ser usado pelo servidor como qualquer outro handler.
- `antes e depois de next.ServeHTTP`: O código antes da chamada roda na entrada. O código depois roda quando o handler interno retorna. Nosso logger usa primeiro a parte de entrada.

#### Referências

- [http.Handler](/reference/go/http-handlers-and-middleware)

## Etapa 2: Conheça o contrato de um handler

**Parte:** Go e biblioteca padrão

### O que vamos fazer

Entender o tipo que permite que o servidor, o router e o middleware se conectem.

### Por que esta etapa importa

O middleware precisa aceitar handlers diferentes sem conhecer o tipo concreto de cada rota. A biblioteca padrão fornece um contrato comum para isso.

### Onde se encaixa

http.Handler pertence à borda HTTP. O ServeMux e os middleware podem trabalhar com esse contrato. Os handlers dos módulos continuam traduzindo a requisição para chamadas da aplicação.

### Código desta etapa

**Arquivo: `net/http (contrato simplificado)`**

```text
package http

type Handler interface {
	ServeHTTP(ResponseWriter, *Request)
}
```

### Detalhes técnicos e de linguagem

http.Handler é uma interface da biblioteca padrão com um único método: ServeHTTP(http.ResponseWriter, *http.Request). Um tipo a satisfaz quando possui um método com essa assinatura; Go não exige uma declaração implements. *http.ServeMux já implementa o contrato. No parâmetro next, a interface carrega o tipo concreto do mux e seu valor. O middleware precisa conhecer apenas ServeHTTP, então também pode receber outro router ou um handler isolado.

#### Trechos e conceitos

- `ServeHTTP(w http.ResponseWriter, r *http.Request)`: w é o destino da resposta. r aponta para os dados da requisição. O asterisco em *http.Request indica um ponteiro para Request.
- `http.Handler`: É o contrato que RequestLogger recebe e devolve. O compilador verifica os métodos do tipo concreto; não existe uma palavra-chave implements para declarar.
- `*http.ServeMux`: O asterisco indica um ponteiro para ServeMux. Esse é o tipo concreto usado no exemplo, mas RequestLogger não depende dele: basta implementar ServeHTTP.

#### Referências

- [Documentação oficial: http.Handler](https://pkg.go.dev/net/http#Handler)
- [interface](/reference/go/interfaces)
- [ponteiros](/reference/go/pointers)
- [http.Handler](/reference/go/http-handlers-and-middleware)

## Etapa 3: Adapte uma função para http.Handler

**Parte:** Go e biblioteca padrão

### O que vamos fazer

Ver por que http.HandlerFunc permite declarar o middleware como uma função anônima.

### Por que esta etapa importa

Criar um tipo e um método para cada pequeno middleware aumentaria o código. A biblioteca padrão já inclui um adaptador para funções com a assinatura HTTP esperada.

### Onde se encaixa

http.HandlerFunc é uma ferramenta da camada HTTP. Ela deixa escrever o comportamento como função e ainda devolver um valor que atende ao contrato http.Handler.

### Código desta etapa

**Arquivo: `internal/platform/httpserver/middleware.go`**

```go
package httpserver

import "net/http"

func example(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// ação antes do próximo handler
		next.ServeHTTP(w, r)
	})
}
```

### Detalhes técnicos e de linguagem

http.HandlerFunc é um tipo de função declarado pela biblioteca padrão. Ele implementa ServeHTTP chamando a própria função. A conversão não executa o corpo: apenas adapta o valor ao contrato http.Handler. A chamada example(next) monta o wrapper e a função anônima captura next. Quando chega uma requisição, o servidor chama ServeHTTP no wrapper; a função então executa e chama next.ServeHTTP. O middleware não recria o handler seguinte a cada request.

#### Trechos e conceitos

- `http.HandlerFunc(func(w, r) { ... })`: A conversão adapta a função ao tipo HandlerFunc, cujo método ServeHTTP chama essa função. Assim ela satisfaz a interface http.Handler.
- `type HandlerFunc func(ResponseWriter, *Request)`: Essa é a forma simplificada do tipo na biblioteca padrão. O método ServeHTTP de HandlerFunc chama a função armazenada, encaminhando w e r. A adaptação é código da biblioteca, não uma regra especial do compilador.
- `next.ServeHTTP(w, r)`: Encaminha a mesma resposta e requisição ao próximo componente. Sem essa chamada, a cadeia para e a rota interna não executa.

#### Referências

- [http.HandlerFunc](/reference/go/http-handlers-and-middleware)
- [closures](https://go.dev/ref/spec#Function_literals)
- [HandlerFunc](https://pkg.go.dev/net/http#HandlerFunc)
- [implementação oficial](https://pkg.go.dev/net/http#HandlerFunc.ServeHTTP)

## Etapa 4: Implemente o RequestLogger

**Parte:** Implementação

### O que vamos fazer

Registrar método e caminho antes de encaminhar a requisição.

### Por que esta etapa importa

Um logger pequeno permite observar que o middleware recebe a requisição antes da rota. Uma única implementação cuida dessa preocupação HTTP compartilhada.

### Onde se encaixa

Neste projeto, o arquivo fica em internal/platform/httpserver porque atende ao servidor como um todo. Essa pasta é uma escolha deste código, não uma exigência do middleware. O limite importante é que a preocupação HTTP não seja puxada para dentro das regras de negócio.

### Estrutura de pastas

- `internal/`
  - `platform/` — Recursos técnicos compartilhados.
    - `httpserver/` — Comportamento HTTP comum à aplicação.
      - `middleware.go` — Middleware que envolve handlers, como o logger.
      - `server.go` — Configuração do servidor HTTP.

### Código desta etapa

**Arquivo: `internal/platform/httpserver/middleware.go`**

```go
package httpserver

import (
	"log"
	"net/http"
)

func RequestLogger(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)
	})
}
```

### Detalhes técnicos e de linguagem

A declaração começa com func, nomeia RequestLogger e recebe next como http.Handler. Como o nome começa com maiúscula, o símbolo é exportado e bootstrap pode chamá-lo por meio do pacote httpserver. A função devolve outro http.Handler. http.HandlerFunc converte a função anônima no adaptador que implementa ServeHTTP; a closure guarda next para usá-lo quando a requisição chegar. Dentro dela, log.Printf registra r.Method e r.URL.Path e next.ServeHTTP(w, r) encaminha a requisição ao handler seguinte. Como o log aparece antes dessa chamada, ele registra a entrada. Se colocarmos outro log depois de next.ServeHTTP, ele roda quando o handler interno retornar. w é o mesmo ResponseWriter entregue à cadeia; este logger não o envolve nem interpreta a resposta.

#### Trechos e conceitos

- `next http.Handler`: É o componente seguinte da cadeia. Depois da conexão ao router, next será o ServeMux que encontra a rota.
- `func RequestLogger(next http.Handler) http.Handler`: func introduz a função; next é o parâmetro; o tipo antes das chaves declara que ela devolve um http.Handler. A interface deixa a função independente do tipo concreto do router.
- `return http.HandlerFunc(func(...))`: A função anônima é adaptada a http.Handler e captura next para usá-lo quando receber uma requisição.
- `r.Method e r.URL.Path`: O log inclui o verbo HTTP e o caminho. Não registra query string, corpo ou cabeçalhos, que não são necessários para este exemplo.

#### Referências

- [closures](/reference/go/http-handlers-and-middleware)
- [http.Request](https://pkg.go.dev/net/http#Request)

## Etapa 5: Conecte o middleware ao router

**Parte:** Composição

### O que vamos fazer

Envolver o router sem alterar os handlers das rotas.

### Por que esta etapa importa

Uma função middleware só participa das requisições depois de conectada à cadeia. O bootstrap é o ponto que reúne as peças concretas da aplicação.

### Onde se encaixa

O ServeMux registra /health e as rotas dos módulos. Devolvê-lo dentro de httpserver.RequestLogger(mux) faz o logger receber todas as requisições destinadas ao router. Neste projeto, bootstrap conecta as peças. Em uma aplicação em camadas, MVC ou com outro router, a mesma chamada fica no ponto que monta o handler entregue ao servidor.

### Código desta etapa

**Arquivo: `internal/bootstrap/router.go`**

```go
package bootstrap

import (
	"net/http"

	"github.com/bendevjunior/hexagonal-architecture-go/internal/platform/httpserver"
)

type RouteRegister interface {
	RegisterRoutes(mux *http.ServeMux)
}

func NewRouter(handlers ...RouteRegister) http.Handler {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /health", httpserver.Health)

	for _, handler := range handlers {
		handler.RegisterRoutes(mux)
	}

	return httpserver.RequestLogger(mux)
}
```

### Detalhes técnicos e de linguagem

O router registra os endpoints antes de envolver o mux. RequestLogger(mux) executa uma vez durante a inicialização e devolve o handler externo que o servidor vai guardar. Quando chega uma requisição, net/http chama ServeHTTP nesse handler com um ResponseWriter e um *Request. A closure registra método e caminho; next.ServeHTTP chama o mux. O mux compara método e caminho, escolhe a rota e chama o handler correspondente. O handler escreve a resposta em w e retorna. O controle então volta ao mux, à closure do logger e ao servidor, nesta ordem. A composição no bootstrap é uma escolha deste projeto; o middleware depende só do contrato http.Handler e também pode envolver outro router.

#### Trechos e conceitos

- `return httpserver.RequestLogger(mux)`: RequestLogger recebe o mux como próximo handler e devolve o componente externo da cadeia.
- `handlers ...RouteRegister`: Os registradores seguem configurando as rotas. O middleware envolve o handler que reúne todas elas; não substitui o registro de endpoints.

#### Referências

- [composição de handlers](/reference/go/http-handlers-and-middleware)
- [interfaces em Go](/reference/go/interfaces)

## Etapa 6: Verifique a cadeia e conheça o limite do exemplo

**Parte:** Verificação e limites

### O que vamos fazer

Confirmar o log e reconhecer o que este middleware ainda não mede.

### Por que esta etapa importa

Seguir a execução ajuda a encontrar erros de encadeamento. Também deixa claro o escopo do exemplo antes de avançar para middleware que tratam mais informações da resposta.

### Onde se encaixa

A requisição entra no RequestLogger, chega ao ServeMux e segue para o handler. O logger básico registra apenas a entrada. Status, duração e recuperação de panic exigem tratamento adicional e ficam para um nível seguinte.

### Fluxo de execução: O que acontece em GET /health

**Chamadas na entrada:**

1. **net/http Server:** Chama o handler configurado no servidor.

   `handler.ServeHTTP(w, r)`
2. **RequestLogger:** Registra método e caminho e encaminha o mesmo w e r.

   `next.ServeHTTP(w, r)`
3. **ServeMux:** Procura a rota que corresponde a GET /health.
4. **httpserver.Health:** Executa a rota e escreve a resposta usando ResponseWriter.

**A pilha retorna nesta ordem:** Health → ServeMux → RequestLogger → Server

As setas de retorno representam o controle voltando das chamadas. O handler não devolve um objeto de resposta: os componentes compartilham w, e o endpoint escreve nele. Código colocado depois de next.ServeHTTP roda durante esse retorno.

### Código desta etapa

**Arquivo: `Terminal`**

```bash
curl.exe http://localhost:8080/health

# No terminal do servidor, deve aparecer:
GET /health
```

### Detalhes técnicos e de linguagem

Faça uma chamada ao health check. A resposta continua sendo produzida pelo endpoint e o processo registra método e caminho. Se aparecer o log, mas a resposta não chegar, confira se next.ServeHTTP(w, r) está presente. Se não houver log, verifique se o servidor recebeu o handler retornado por NewRouter.

#### Trechos e conceitos

- `Coberto`: Método e caminho são registrados antes da execução da rota.
- `Fica para outro nível`: Capturar status, duração, identificador de requisição e panic envolve decisões adicionais. O logger apresentado não oferece essas garantias.

#### Referências

- [http.Handler](/reference/go/http-handlers-and-middleware)

