Como construir uma API REST com Go e Gin em 2026: guia completo

Gocom oGim framework é uma das maneiras mais rápidas e limpas de construir APIs REST em 2026 – desempenho compilado, sintaxe simples e um ecossistema maduro. Este guia cria uma API completa com roteamento, validação, acesso a banco de dados e middleware.

Por que ir e Gin?

• Desempenho: Compiled Go lida com alta simultaneidade com recursos mínimos
• Implantação simples: Um único binário estático — sem tempo de execução para instalar
• Velocidade do Gin: Um dos frameworks web Go mais rápidos, com uma API limpa
• Ótimo para microsserviços: Binários pequenos, inicialização rápida, pouca memória

Configuração

mkdir go-api && cd go-api
go mod init github.com/you/go-api
go get github.com/gin-gonic/gin
go get gorm.io/gorm gorm.io/driver/postgres

Servidor Básico e Roteamento

// main.go
package main

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

func main() {
    r := gin.Default()   // includes logger and recovery middleware

    r.GET("/health", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"status": "ok"})
    })

    // Route groups
    api := r.Group("/api/v1")
    {
        api.GET("/users", getUsers)
        api.GET("/users/:id", getUser)
        api.POST("/users", createUser)
        api.PUT("/users/:id", updateUser)
        api.DELETE("/users/:id", deleteUser)
    }

    r.Run(":8080")
}

Modelos e Banco de Dados

// models.go
package main

import "gorm.io/gorm"

type User struct {
    ID    uint   `json:"id" gorm:"primaryKey"`
    Name  string `json:"name" binding:"required"`
    Email string `json:"email" binding:"required,email" gorm:"unique"`
}

var db *gorm.DB

func initDB() {
    dsn := "host=localhost user=postgres password=pass dbname=mydb port=5432"
    var err error
    db, err = gorm.Open(postgres.Open(dsn), &gorm.Config{})
    if err != nil {
        panic("failed to connect database")
    }
    db.AutoMigrate(&User{})
}

Manipuladores com vinculação e validação JSON

// handlers.go
func getUsers(c *gin.Context) {
    var users []User
    db.Find(&users)
    c.JSON(http.StatusOK, users)
}

func getUser(c *gin.Context) {
    var user User
    if err := db.First(&user, c.Param("id")).Error; err != nil {
        c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
        return
    }
    c.JSON(http.StatusOK, user)
}

func createUser(c *gin.Context) {
    var user User
    // Binds JSON and runs validation tags (required, email)
    if err := c.ShouldBindJSON(&user); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    if err := db.Create(&user).Error; err != nil {
        c.JSON(http.StatusConflict, gin.H{"error": "email already exists"})
        return
    }
    c.JSON(http.StatusCreated, user)
}

Middleware personalizado

// Authentication middleware
func authRequired() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "missing token"})
            c.Abort()   // stop the chain
            return
        }
        userID, err := verifyToken(token)
        if err != nil {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
            c.Abort()
            return
        }
        c.Set("userID", userID)  // pass to handlers
        c.Next()
    }
}

// Apply to a route group
protected := r.Group("/api/v1")
protected.Use(authRequired())

Tratamento estruturado de erros

// Consistent error responses
type APIError struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
}

func respondError(c *gin.Context, code int, msg string) {
    c.JSON(code, APIError{Code: code, Message: msg})
}

// Recovery middleware (Gin includes one, but you can customize)
r.Use(gin.CustomRecovery(func(c *gin.Context, recovered interface{}) {
    respondError(c, http.StatusInternalServerError, "internal server error")
}))

Desligamento Gracioso

func main() {
    r := setupRouter()
    srv := &http.Server{Addr: ":8080", Handler: r}

    go func() {
        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            log.Fatalf("listen: %s\n", err)
        }
    }()

    // Wait for interrupt signal
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
    <-quit

    // Graceful shutdown with 5-second timeout
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    srv.Shutdown(ctx)
}

Perguntas Frequentes

P: Gin vs Echo vs Fibra?
R: Todos são rápidos e maduros. Gin é o mais popular com o maior ecossistema. Eco é semelhante. Fiber tem uma API semelhante ao Express. Para a maioria dos projetos, a popularidade e a documentação do Gin o tornam o padrão seguro.

P: GORM ou SQL/sqlx bruto?
R: GORM é conveniente para CRUD e desenvolvimento rápido. Para consultas complexas ou máximo controle e desempenho, é preferível SQL bruto com sqlx ou pgx. Muitas equipes usam GORM para o básico e passam para SQL bruto quando necessário.

P: Como posso validar os dados da solicitação?
R: Gin usa tags struct com a biblioteca validadora —binding:"required,email". ShouldBindJSON executa a validação automaticamente e retorna erros que você pode retornar ao cliente.

P: Como faço para lidar com o CORS no Gin?
R: Use o middleware gin-contrib/cors:r.Use(cors.Default()) para desenvolvimento permissivo ou configure origens, métodos e cabeçalhos específicos para produção.

P: Como faço para testar manipuladores de Gin?
R: Use httptest para criar uma solicitação de teste e um gravador e, em seguida, afirme a resposta. O roteador do Gin funciona com as ferramentas de teste padrão do Go para testes de manipulação limpos e rápidos.

Conclusão

Go with Gin oferece APIs REST rápidas e limpas que são compiladas em um único binário implantável. Este guia cobre o essencial – grupos de rotas, ligação JSON com validação, acesso ao banco de dados GORM, middleware personalizado para autenticação, erros estruturados e desligamento normal. O desempenho e a implantação simples do Go o tornam excelente para microsserviços e APIs de alta simultaneidade. Adicione limitação de taxa, registro estruturado e documentos OpenAPI antes da produção e você terá um back-end robusto e escalonável.