Noções Básicas de Web Frameworks

10 exemplos para você começar com Web Frameworks - 7 básicos e 3 intermediários.

Pré-requisitos

• Instale o Go 1.26.x ou posterior em go.dev/dl.
• Crie um módulo: mkdir webdemo && cd webdemo && go mod init example.com/webdemo.
• Adicione dependências conforme necessário: go get github.com/go-chi/chi/v5 e go get github.com/gin-gonic/gin.
• Execute os exemplos com go run . após salvar como main.go (ou divida os arquivos no mesmo módulo).

Exemplos Básicos

1. Handler hello da biblioteca padrão

A base sobre a qual todos os frameworks são construídos: http.HandlerFunc.

package main
 
import (
    "fmt"
    "net/http"
)
 
func main() {
    http.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "hello, stdlib")
    })
    http.ListenAndServe(":8080", nil)
}

• http.HandleFunc registra no DefaultServeMux.
• Handlers recebem ResponseWriter e Request - o contrato universal.
• Prefira http.Server explícito em produção; este mostra a forma menor.

Relacionado: net/http: A Pilha HTTP Incluída do Go - modelo HTTP da biblioteca padrão

2. Roteador chi com uma rota GET

chi permanece compatível com http.Handler, adicionando parâmetros de caminho.

package main
 
import (
    "net/http"
 
    "github.com/go-chi/chi/v5"
)
 
func main() {
    r := chi.NewRouter()
    r.Get("/ping", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("pong"))
    })
    http.ListenAndServe(":8080", r)
}

• chi.NewRouter() retorna um http.Handler que você passa para ListenAndServe.
• Métodos de rota (Get, Post) definem restrições de verbo HTTP.
• Nenhum contexto específico do framework - handlers se parecem com código da biblioteca padrão.

Relacionado: chi: Roteamento e Middleware Leves - grupos de rotas e middleware

3. Parâmetro de URL chi

Segmentos nomeados aparecem no padrão e são lidos da requisição.

r.Get("/users/{id}", func(w http.ResponseWriter, r *http.Request) {
    id := chi.URLParam(r, "id")
    w.Write([]byte("user " + id))
})

• {id} vincula um segmento de caminho; use {id:*} para caminhos rest gananciosos quando necessário.
• chi.URLParam retorna uma string vazia se a chave estiver ausente - valide antes de usar.
• Nomes de parâmetros são por rota; documente-os no OpenAPI ou em tabelas de rotas.

Relacionado: Frameworks HTTP Go: Roteadores vs. Frameworks Completos - modelo de roteador vs. framework

4. Cadeia de middleware chi

Use envolve todas as rotas registradas após ele naquele roteador.

import "github.com/go-chi/chi/v5/middleware"
 
r.Use(middleware.RequestID)
r.Use(middleware.Logger)
r.Get("/time", func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("ok"))
})

• A ordem do middleware importa: o primeiro Use é o mais externo na entrada.
• chi fornece middleware comuns: ID de requisição, recuperador, timeout, compressão.
• Escreva middleware personalizado como func(http.Handler) http.Handler.

Relacionado: Padrões de Middleware e Decorador - modelo de encapsulamento de handler

5. Grupo de rotas chi com prefixo

Monte rotas relacionadas sob um caminho e middleware compartilhados.

r.Route("/api/v1", func(r chi.Router) {
    r.Get("/health", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte(`{"status":"ok"}`))
    })
    r.Get("/version", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte(`{"version":"1"}`))
    })
})

• Route cria um sub-roteador que herda o middleware pai, a menos que você ramifique mais cedo.
• Os prefixos se empilham: /api/v1/health corresponde ao handler de saúde.
• Grupos mantêm as tags OpenAPI e os limites de autenticação alinhados com a estrutura do URL.

6. Motor padrão Gin e rota JSON

Gin usa *gin.Context em vez de http.ResponseWriter bruto.

package main
 
import "github.com/gin-gonic/gin"
 
func main() {
    g := gin.Default() // Middleware Logger + Recovery
    g.GET("/ping", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "pong"})
    })
    g.Run(":8080")
}

• gin.Default() habilita o middleware de log de depuração - use gin.New() mais middleware explícito em ajuste de produção.
• c.JSON define Content-Type e codifica o mapa.
• gin.H é um atalho para map[string]any para cargas úteis pequenas.

Relacionado: Gin: APIs JSON Rápidas e Binding - binding e validação

7. Parâmetro de caminho Gin

O contexto do framework expõe parâmetros com Param.

g.GET("/users/:id", func(c *gin.Context) {
    id := c.Param("id")
    c.JSON(200, gin.H{"id": id})
})

• Gin usa a sintaxe :id; chi usa {id} - a migração requer reescrita de caminhos ou adaptadores.
• Parâmetros são sempre strings; analise inteiros com strconv ou helpers de binding.
• Rotas curinga usam *path com semântica ligeiramente diferente de {path:*} do chi.

Exemplos Intermediários

8. Binding JSON Gin em POST

Faça o binding de corpos de requisição em structs com tags.

type createUser struct {
    Email string `json:"email" binding:"required,email"`
}
 
g.POST("/users", func(c *gin.Context) {
    var in createUser
    if err := c.ShouldBindJSON(&in); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    c.JSON(201, gin.H{"email": in.Email})
})

• ShouldBindJSON evita escrita dupla de respostas em caso de falha (prefira sobre BindJSON em handlers).
• Tags de validação precisam de github.com/go-playground/validator integrado através do Gin.
• Mantenha structs DTO em um pacote api ou transport separado dos modelos de domínio.

9. Sub-roteador chi montado em um caminho

Monte roteadores independentes para serviços modulares.

admin := chi.NewRouter()
admin.Get("/stats", func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("stats"))
})
 
r.Mount("/admin", admin)

• Mount remove o prefixo antes que o sub-roteador corresponda.
• Cada roteador montado pode carregar sua própria pilha de middleware.
• Útil para dividir admin, API pública e webhooks em um único binário.

10. Handler de negócios compartilhado por trás de dois roteadores

Escreva a lógica uma vez como http.HandlerFunc, registre no chi; Gin precisa de um adaptador fino.

func showHealth(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.Write([]byte(`{"ok":true}`))
}
 
// chi
r.Get("/health", showHealth)
 
// adaptador gin
g.GET("/health", func(c *gin.Context) {
    showHealth(c.Writer, c.Request)
})

• Handlers portáteis facilitam a migração entre roteadores.
• c.Writer e c.Request do Gin são os tipos subjacentes da biblioteca padrão.
• Para aplicativos maiores, monte um chi.Router inteiro sob o Gin ou vice-versa em vez de adaptadores por rota.

Relacionado: Migrando Entre Roteadores Sem Reescrever Handlers - padrões de adaptador

Versões da Pilha: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (mais recente - verifique na compilação), gin (mais recente - verifique na compilação), echo (mais recente - verifique na compilação), google.golang.org/grpc (mais recente - verifique na compilação), sigs.k8s.io/controller-runtime (mais recente - verifique na compilação), kubebuilder (mais recente - verifique na compilação), tinygo (mais recente - verifique os alvos de placa na compilação), wazero (mais recente - verifique na compilação) e golangci-lint (mais recente - verifique o conjunto de linters na compilação).