Concepto clave

Configurar un proyecto Go con gorilla/mux es como preparar los cimientos de un edificio: si la base es sólida, todo lo que construyas encima será estable y escalable. En el contexto de APIs REST, esto significa establecer una estructura de proyecto limpia, gestionar dependencias correctamente y configurar el enrutador que dirigirá todas las peticiones HTTP.

Imagina que estás organizando una cocina profesional: primero necesitas definir dónde irán los utensilios (estructura de carpetas), luego asegurarte de tener todos los ingredientes (dependencias), y finalmente preparar la estación de trabajo (enrutador) donde prepararás cada plato (endpoint). Gorilla/mux es tu enrutador HTTP principal, que te permite definir rutas con mayor flexibilidad que el enrutador estándar de Go, incluyendo parámetros en las URLs, validaciones y middlewares.

Cómo funciona en la práctica

Vamos a crear un proyecto desde cero. Primero, asegúrate de tener Go instalado (versión 1.16 o superior recomendada). Crea un directorio para tu proyecto, por ejemplo api-microservicio, y dentro de él, inicializa el módulo Go:

mkdir api-microservicio
cd api-microservicio
go mod init github.com/tu-usuario/api-microservicio

Luego, instala gorilla/mux usando go get. Este comando descargará la biblioteca y la agregará a tu archivo go.mod:

go get github.com/gorilla/mux

Ahora, crea la estructura básica de carpetas. Una organización común es:

cmd/ para el punto de entrada de la aplicación (ej: cmd/main.go)
internal/ para código privado de tu proyecto
pkg/ para código que podría ser reutilizado en otros proyectos (opcional)
go.mod y go.sum generados automáticamente

En cmd/main.go, importa gorilla/mux y configura un enrutador básico. Esto establece la base sobre la que agregarás endpoints específicos en lecciones futuras.

Código en acción

Aquí tienes un ejemplo funcional de un servidor mínimo con gorilla/mux. Crea el archivo cmd/main.go con este contenido:

package main

import (
    "fmt"
    "log"
    "net/http"
    "github.com/gorilla/mux"
)

func main() {
    // Inicializar el enrutador
    r := mux.NewRouter()
    
    // Definir una ruta simple
    r.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "¡API con gorilla/mux funcionando!")
    }).Methods("GET")
    
    // Configurar el servidor
    port := ":8080"
    fmt.Printf("Servidor escuchando en http://localhost%s\n", port)
    log.Fatal(http.ListenAndServe(port, r))
}

Para ejecutarlo, usa:

go run cmd/main.go

Ahora, mejoremos la estructura. En lugar de tener toda la lógica en main, separamos la configuración del enrutador. Crea un archivo internal/router/router.go:

package router

import (
    "github.com/gorilla/mux"
)

func NewRouter() *mux.Router {
    r := mux.NewRouter()
    r.HandleFunc("/", homeHandler).Methods("GET")
    return r
}

func homeHandler(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("API estructurada correctamente"))
}

Y actualiza cmd/main.go para usar este router:

package main

import (
    "fmt"
    "log"
    "net/http"
    "github.com/tu-usuario/api-microservicio/internal/router"
)

func main() {
    r := router.NewRouter()
    port := ":8080"
    fmt.Printf("Servidor escuchando en http://localhost%s\n", port)
    log.Fatal(http.ListenAndServe(port, r))
}

Errores comunes

No usar go modules: Algunos desarrolladores intentan trabajar con GOPATH, pero para proyectos modernos, siempre inicializa con go mod init. Esto gestiona dependencias de forma reproducible.
Olvidar Methods() en las rutas: Gorilla/mux requiere especificar los métodos HTTP (GET, POST, etc.). Si lo omites, la ruta responderá a todos los métodos, lo que puede causar comportamientos inesperados.
No manejar CORS en desarrollo: Para APIs que serán consumidas por frontends, configura middlewares para CORS desde el inicio, evitando problemas de conexión cruzada.
Estructura de proyecto plana: Evita poner todo en un solo archivo. Usa carpetas como cmd, internal para mantener el código organizado y escalable.
Ignorar el archivo go.sum: Este archivo asegura la integridad de las dependencias. Nunca lo elimines manualmente; déjalo que Go lo gestione automáticamente.

Checklist de dominio

✓ Inicialicé un módulo Go con go mod init
✓ Instalé gorilla/mux usando go get
✓ Creé una estructura de carpetas básica (cmd/, internal/)
✓ Configuré un enrutador con al menos una ruta GET
✓ Separé la lógica del enrutador en un paquete interno
✓ Probé que el servidor responde en localhost:8080
✓ Verifiqué que go.mod y go.sum están actualizados

Configura un proyecto Go con gorilla/mux desde cero

Sigue estos pasos para crear un proyecto funcional que sirva como base para tu API:

Crea un nuevo directorio llamado mi-api y navega a él en tu terminal.
Inicializa el módulo Go con un nombre de tu elección (ej: go mod init github.com/tu-usuario/mi-api).
Instala gorilla/mux ejecutando go get github.com/gorilla/mux.
Crea la estructura de carpetas: cmd/ y internal/router/.
En internal/router/router.go, define una función NewRouter que cree un enrutador con dos rutas:
- Una ruta /health con método GET que responda con JSON: {"status": "ok"}
- Una ruta /version con método GET que responda con la versión de tu API (ej: {"version": "1.0.0"})
En cmd/main.go, importa tu router y levanta el servidor en el puerto 3000.
Ejecuta el proyecto con go run cmd/main.go y verifica que ambas rutas funcionen usando curl o un navegador.

Pistas

Usa w.Header().Set("Content-Type", "application/json") para las respuestas JSON
Recuerda importar "encoding/json" si necesitas usar json.Marshal
Puedes definir constantes para los mensajes de respuesta en el paquete router

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.

Configuración inicial de un proyecto Go con gorilla/mux