Visualizar onde uma preocupação compartilhada entra no caminho de uma requisição.
Por que fazemos assim
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 isso se encaixa na arquitetura
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.
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.
Entenda os detalhes de Go usados aqui
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.
Trecho / conceitoPor que existe / o que acontece
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.
A trilha guiada continua acima. Abra qualquer etapa abaixo para consultar o conteúdo completo na ordem do curso.
Etapa 1 de 6: O que é um middleware HTTP?· Conceito
Etapa 1 de 6 · Conceito
O que é um middleware HTTP?
O que vamos fazer
Visualizar onde uma preocupação compartilhada entra no caminho de uma requisição.
Por que fazemos assim
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 isso se encaixa na arquitetura
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.
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.
Entenda os detalhes de Go usados aqui
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.
Trecho / conceitoPor que existe / o que acontece
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.
Etapa 2 de 6: Conheça o contrato de um handler· Go e biblioteca padrão
Etapa 2 de 6 · Go e biblioteca padrão
Conheça o contrato de um handler
O que vamos fazer
Entender o tipo que permite que o servidor, o router e o middleware se conectem.
Por que fazemos assim
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 isso se encaixa na arquitetura
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
Gonet/http (contrato simplificado)
package http
type Handler interface {
ServeHTTP(ResponseWriter, *Request)
}
Entenda os detalhes de Go usados aqui
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.
Trecho / conceitoPor que existe / o que acontece
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.
Etapa 3 de 6: Adapte uma função para http.Handler· Go e biblioteca padrão
Etapa 3 de 6 · Go e biblioteca padrão
Adapte uma função para http.Handler
O que vamos fazer
Ver por que http.HandlerFunc permite declarar o middleware como uma função anônima.
Por que fazemos assim
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 isso se encaixa na arquitetura
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
Gointernal/platform/httpserver/middleware.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)
})
}
Entenda os detalhes de Go usados aqui
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.
Trecho / conceitoPor que existe / o que acontece
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.
Etapa 4 de 6: Implemente o RequestLogger· Implementação
Etapa 4 de 6 · Implementação
Implemente o RequestLogger
O que vamos fazer
Registrar método e caminho antes de encaminhar a requisição.
Por que fazemos assim
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 isso se encaixa na arquitetura
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
▸ platformRecursos técnicos compartilhados.
▸ httpserverComportamento HTTP comum à aplicação.
↳ middleware.goMiddleware que envolve handlers, como o logger.
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.
Trecho / conceitoPor que existe / o que acontece
next http.Handler
É o componente seguinte da cadeia. Depois da conexão ao router, next será o ServeMux que encontra a rota.
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.
Etapa 5 de 6: Conecte o middleware ao router· Composição
Etapa 5 de 6 · Composição
Conecte o middleware ao router
O que vamos fazer
Envolver o router sem alterar os handlers das rotas.
Por que fazemos assim
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 isso se encaixa na arquitetura
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.
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.
Trecho / conceitoPor que existe / o que acontece
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.
Etapa 6 de 6: Verifique a cadeia e conheça o limite do exemplo· Verificação e limites
Etapa 6 de 6 · Verificação e limites
Verifique a cadeia e conheça o limite do exemplo
O que vamos fazer
Confirmar o log e reconhecer o que este middleware ainda não mede.
Por que fazemos assim
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 isso se encaixa na arquitetura
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.
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
GoTerminal
curl.exe http://localhost:8080/health
# No terminal do servidor, deve aparecer:
GET /health
Entenda os detalhes de Go usados aqui
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.
Trecho / conceitoPor que existe / o que acontece
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.