API REST con Go — Gin o Echo per Scegliere il Framework Giusto e le Best Practice che Funzionano

Hai un servizio Go da esporre, ma scegliere tra Gin e Echo ti sta bloccando. Oppure hai già scelto e scopri che le route diventano un groviglio, la validazione è manuale e il middleware si accumula senza controllo. Noi ci siamo passati. Su progetti con decine di endpoint, autenticazione, rate limiting e logging strutturato, abbiamo dovuto decidere e poi ottimizzare. In questa guida vediamo come scegliere il framework, come impostare una struttura solida e quali best practice applicare subito — con codice reale.

Perché Gin e Echo Dominano le API REST in Go?

Entrambi sono framework minimalisti che non rinunciano alla performance. Gin si basa su httprouter, Echo su un router proprietario. La differenza? Gin è più diffuso, ha più middleware pre-costruiti e una curva di apprendimento leggermente più bassa. Echo è più esplicito, con un'API che molti trovano più elegante e una gestione degli errori integrata che Gin non ha. Noi usiamo entrambi a seconda del progetto. La scelta dipende da quanto controllo vuoi sul ciclo di vita della richiesta.

Best practice: non scegliere in base alla moda. Scarica entrambi, lancia il benchmark di esempio e vedi quale sintassi ti è più naturale. Per un'API semplice, Echo ti dà meno sorprese. Per un'API complessa con molto middleware personalizzato, Gin ti lascia più libertà.

Cosa fare subito

Installa entrambi e crea un endpoint hello world in 5 minuti. Poi confronta la gestione degli errori: Echo ha c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()}) già integrato, Gin richiede c.AbortWithStatusJSON. Scegli quello che ti sembra più pulito.

Come Strutturare un Progetto API REST con Go per non Perderci la Testa?

Il problema più comune che vediamo nei team che ci chiedono consulenza: tutto in un file main.go con 2000 righe. Non si può mantenere. Noi abbiamo importato dal nostro lavoro con Laravel e Livewire un pattern a strati: handler, service, repository. Non è obbligatorio, ma per API con più di 10 endpoint è salva-vita.

Struttura consigliata:

progetto-api/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── handler/
│   │   └── user.go
│   ├── service/
│   │   └── user.go
│   ├── repository/
│   │   └── user.go
│   ├── middleware/
│   │   └── auth.go
│   └── model/
│       └── user.go
├── pkg/
│   └── config/
│       └── config.go
└── go.mod

Ogni strato ha una responsabilità unica. Handler: parsing della richiesta e risposta HTTP. Service: logica di business. Repository: accesso ai dati (DB, API esterna). Middleware: logging, autenticazione, CORS. Questo pattern lo usiamo anche nei progetti Go che sviluppiamo per clienti con fatturato reale: ti permette di testare ogni strato separatamente.

Esempio con Gin: handler + service

// internal/handler/user.go
package handler

import (
	"net/http"
	"github.com/gin-gonic/gin"
	"progetto-api/internal/service"
)

type UserHandler struct {
	svc *service.UserService
}

func NewUserHandler(svc *service.UserService) *UserHandler {
	return &UserHandler{svc: svc}
}

func (h *UserHandler) GetUser(c *gin.Context) {
	id := c.Param("id")
	user, err := h.svc.GetUser(id)
	if err != nil {
		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, user)
}

Middleware, Validazione e Autenticazione — Quali Best Practice Adottare?

Un'API REST senza middleware è una porta aperta. Noi vediamo spesso progetti che arrivano da altri sviluppatori senza rate limiting, senza logging strutturato, con validazione affidata solo al frontend. Sbagliato. Ogni richiesta deve passare da un middleware che logga metodo, percorso, durata e status. Poi autenticazione (JWT o API key). Poi validazione dei campi in input.

Middleware di logging con Echo

// internal/middleware/logger.go
package middleware

import (
	"log"
	"time"
	"github.com/labstack/echo/v4"
)

func RequestLogger() echo.MiddlewareFunc {
	return func(next echo.HandlerFunc) echo.HandlerFunc {
		return func(c echo.Context) error {
			start := time.Now()
			err := next(c)
			log.Printf("%s %s %d %s", c.Request().Method, c.Path(), c.Response().Status, time.Since(start))
			return err
		}
	}
}

Validazione con strutture Go

Usa i tag di validazione di go-playground/validator. Sia Gin che Echo lo supportano nativamente con binding e validate.

type CreateUserRequest struct {
	Name  string `json:"name" binding:"required,min=3"`
	Email string `json:"email" binding:"required,email"`
	Age   int    `json:"age" binding:"gte=18"`
}

// Nel handler
var req CreateUserRequest
if err := c.ShouldBindJSON(&req); err != nil {
	c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
	return
}

Gestione degli Errori e Risposte Uniformi — Come Mantenere Coerenza?

Niente di peggio di un'API che risponde a volte con {"error":"not found"}, a volte con {"message":"404"}. Noi definiamo una struttura di risposta standard: {"success":bool, "data":interface{}, "error":string}. E un middleware che intercetta gli errori non gestiti e li uniforma. Con Echo questo è integrato con HTTPErrorHandler. Con Gin devi creare un middleware globale.

Esempio con Gin: risposta standard

// pkg/response/response.go
package response

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

type APIResponse struct {
	Success bool        `json:"success"`
	Data    interface{} `json:"data,omitempty"`
	Error   string      `json:"error,omitempty"`
}

func Success(c *gin.Context, data interface{}) {
	c.JSON(http.StatusOK, APIResponse{Success: true, Data: data})
}

func Error(c *gin.Context, status int, message string) {
	c.JSON(status, APIResponse{Success: false, Error: message})
}

Cosa Fare Adesso

1. Scarica Gin e Echo e crea un endpoint di test con entrambi. Scegli quello che ti fa scrivere meno codice per il tuo caso.
2. Struttura il progetto con handler/service/repository. Anche per un'API piccola, dividi le responsabilità.
3. Aggiungi middleware di logging, autenticazione e rate limiting prima di qualsiasi logica di business.
4. Implementa risposte uniformi con un pacchetto response condiviso.
5. Approfondisci il pillar principale: Go per Backend — API REST e Microservizi.

Per documentazione ufficiale: Gin Docs e Echo Docs.