Aprendendo · Go

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.

Básico em Go e HTTP · 6 etapas

Comece pela primeira etapa

GitHub

Código-fonte do tutorial

GitHub ↗
git clone https://github.com/bendevjunior/hexagonal-architecture-go

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

  1. Handler da rota
  2. Router
  3. Middleware
  4. 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.

Referência: handlers e middleware em net/http →

Conteúdo completo do curso

A trilha guiada continua acima. Abra qualquer etapa abaixo para consultar o conteúdo completo na ordem do curso.

  1. 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

    1. Handler da rota
    2. Router
    3. Middleware
    4. 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.

    Referência: handlers e middleware em net/http →

  2. 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.

    Documentação oficial: http.Handler →

  3. 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.

    Referência: http.HandlerFunc e closures →

  4. 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.
          • ↳ server.goConfiguração do servidor HTTP.

    Código desta etapa

    Gointernal/platform/httpserver/middleware.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)
    	})
    }
    Entenda os detalhes de Go usados aqui

    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 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ência técnica: handlers HTTP em Go →

  5. 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.

    Código desta etapa

    Gointernal/bootstrap/router.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)
    }
    Entenda os detalhes de Go usados aqui

    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.

    Referência: composição de middleware →

  6. 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

    1. Health
    2. ServeMux
    3. RequestLogger
    4. 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.

    Fontes oficiais e referência completa →

Consulte também a referência técnica independente. Abrir referências de Go