A interface padrão http.Handler no Go estabelece um contrato para processar requisições HTTP. Ela requer a implementação do método ServeHTTP, que manipula a resposta e a solicitação. O servidor HTTP utiliza essa interface para despachar requisições para handlers registrados.

package http

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

// ListenAndServe inicializa um servidor HTTP no endereço especificado, delegando requisições ao handler fornecido.
func ListenAndServe(address string, h Handler) error

Abordagem do Gin para o Handler

O framework Gin implementa http.Handler através de sua estrutura Engine. O método ServeHTTP da Engine gerencia um pool de contextos para eficiência e orquestra o roteamento das requisições.

Ao inicializar uma aplicação com gin.Default(), middlewares essenciais como Logger e Recovery são acoplados. A estrutura Engine contém uma árvore de roteamento para cada método HTTP, permitindo a correspondência rápida de caminhos.

Exemplo de Aplicação com o Gin

O código a seguir demonstra a configuração básica de um serivdor Gin. Observe a definição de uma rota POST que lida com dados JSON.

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

type Credenciais struct {
    Usuario string `json:"usuario"`
    Senha   string `json:"senha"`
}

func main() {
    // Cria uma instância do motor Gin com middlewares padrão
    servidor := gin.Default()

    // Define uma rota para autenticação via JSON
    servidor.POST("/autenticar", func(ctx *gin.Context) {
        var dados Credenciais
        if falha := ctx.ShouldBindJSON(&dados); falha != nil {
            ctx.JSON(http.StatusBadRequest, gin.H{"erro": falha.Error()})
            return
        }

        ctx.JSON(http.StatusOK, gin.H{"mensagem": "autenticação bem-sucedida"})
    })

    // Inicia o servidor na porta 8080
    servidor.Run(":8080")
}

Funcionamento Interno do Roteamento

Ao receber uma requisição, o método ServeHTTP da Engine recupera um contexto do pool, inicializa-o com os dados da requisição e chama handleHTTPRequest. Este último localiza a rota correspondente na árvore de métodos HTTP, executando a cadeia de handlers associada. Se nenhum handler for encontrado, respostas de erro (404 ou 405) são geradas.

A estrutura do Engine é configurada com opções como redirecionamento de barra final e tratamento de caminhos, as quais influenciam na resolução das rotas. A árvore de roteamento (trees) é organizada por método HTTP, permitindo buscas eficientes para determinar os handlers corretos.

Inserção de Rotas na Estrutura

Quando uma rota é definida, como no exemplo do servidor.POST, o handler é adicionado à árvore de roteamento. O caminho absoluto é calculado com base no grupo de roteamento, e a cadeia de handlers é combinada com quaisquer middlewares aplicados. Este processo garante que a requisição seja processada pela sequência correta de funções.