Práctica: Crear una API básica de gestión de usuarios

Introducción: Construyendo Nuestro Primer Microservicio

En esta lección práctica, consolidaremos los fundamentos teóricos de las APIs REST aplicándolos en Go con la ayuda del poderoso router gorilla/mux. Vamos a construir desde cero una API básica para la gestión de usuarios, un componente universal en prácticamente cualquier sistema moderno. Este ejercicio no solo te familiarizará con la definición de rutas y manejadores, sino que también sentará las bases para entender el flujo de una petición HTTP en un entorno Go, desde el enrutamiento hasta la serialización de la respuesta.

El objetivo final es una API funcional con operaciones CRUD (Crear, Leer, Actualizar, Eliminar) que maneje un recurso "Usuario". Utilizaremos una slice en memoria para simular una base de datos, lo que nos permite concentrarnos en la lógica HTTP y la estructura del proyecto. Al final de esta lección, tendrás un servidor corriendo localmente capaz de responder a solicitudes GET, POST, PUT y DELETE, formateando las respuestas en JSON, el estándar de facto para la comunicación entre servicios.

Este es el primer paso tangible hacia la construcción de microservicios en Go. La elección de gorilla/mux se debe a su flexibilidad, rendimiento y rico conjunto de características para enrutamiento complejo, que supera con creces el router por defecto del paquete `net/http`. Aprender a estructurar tu código de manera clara y mantenible desde el principio es crucial para escalar la aplicación en el futuro.

Concepto Clave: El Enrutador como Director de Tráfico

Imagina una gran central de correos en una ciudad importante. Los paquetes (peticiones HTTP) llegan constantemente desde diferentes lugares, cada uno con una dirección de destino (URL y método como GET /users). El enrutador, en nuestro caso gorilla/mux, actúa como el jefe de planta que lee esas direcciones y decide de manera eficiente y precisa a qué cinta transportadora específica (handler o manejador) debe enviar cada paquete para su procesamiento. Sin este director, los paquetes se amontonarían en la entrada sin rumbo, o todos irían al mismo lugar causando caos.

La potencia de gorilla/mux radica en su capacidad para hacer coincidir patrones de URL complejos, extraer variables de la ruta (como `/users/{id}`), y definir restricciones (por método HTTP, esquema, o incluso headers). Esto nos permite diseñar APIs limpias y expresivas, como las que vemos en servicios populares. Un enrutador básico solo verifica prefijos, pero mux nos permite un control granular, esencial para APIs RESTful donde `/users/1` y `/users/2` son recursos distintos manejados por la misma lógica pero con datos diferentes.

En el contexto de nuestra API de usuarios, el enrutador será el responsable de mapear, por ejemplo, una petición `POST /users` a la función `CreateUser`, y una petición `GET /users/{id}` a la función `GetUser`. Esta separación de preocupaciones (enrutamiento vs. lógica de negocio) es un pilar de la arquitectura de software limpia y mantenible.

Cómo Funciona en la Práctica: Paso a Paso

Vamos a desglosar el proceso de creación de nuestra API en pasos concretos y secuenciales. Primero, inicializamos un nuevo módulo de Go con `go mod init` para gestionar nuestras dependencias. Luego, instalamos la biblioteca gorilla/mux ejecutando `go get github.com/gorilla/mux`. Con el entorno listo, comenzamos a escribir nuestro archivo `main.go`.

El primer bloque de código define la estructura de nuestro recurso principal, el Usuario, utilizando etiquetas struct para controlar cómo se serializa a JSON. A continuación, inicializamos el router con `mux.NewRouter()` y definimos nuestras rutas utilizando métodos como `HandleFunc`. Cada ruta se asocia a una función manejadora que recibe un `http.ResponseWriter` y un `*http.Request`. Dentro de estas funciones, leemos el cuerpo de la petición (para POST/PUT), accedemos a variables de la ruta, interactuamos con nuestro "almacén" en memoria (una slice), y escribimos la respuesta JSON con el código de estado HTTP apropiado.

Finalmente, pasamos nuestro router a la función `http.ListenAndServe`, que pone en marcha el servidor HTTP. El router de gorilla/mux implementa la interfaz `http.Handler`, por lo que se integra perfectamente con el servidor estándar. A partir de este momento, el servidor escucha en el puerto especificado, y cada petición entrante es dirigida por el router al manejador correspondiente, donde se ejecuta nuestra lógica de negocio para gestionar usuarios.

Código en Acción: La API Completa

A continuación, presentamos el código completo y funcional de nuestra API básica de gestión de usuarios. Puedes copiar este código en un archivo `main.go`, ejecutar `go run main.go` y comenzar a probar los endpoints con herramientas como curl o Postman.

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "strconv"
    "sync"
    "github.com/gorilla/mux"
)

// User define la estructura de nuestro recurso.
type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

var (
    users  = []User{}
    nextID = 1
    mu     sync.RWMutex // Mutex para proteger el acceso concurrente a la slice.
)

func main() {
    // Inicializamos el router de gorilla/mux.
    r := mux.NewRouter()

    // Definimos las rutas de nuestra API REST.
    r.HandleFunc("/users", GetUsers).Methods("GET")
    r.HandleFunc("/users", CreateUser).Methods("POST")
    r.HandleFunc("/users/{id}", GetUser).Methods("GET")
    r.HandleFunc("/users/{id}", UpdateUser).Methods("PUT")
    r.HandleFunc("/users/{id}", DeleteUser).Methods("DELETE")

    // Iniciamos el servidor en el puerto 8080.
    log.Println("Servidor API de usuarios iniciado en http://localhost:8080")
    log.Fatal(http.ListenAndServe(":8080", r))
}

// GetUsers responde con la lista completa de usuarios.
func GetUsers(w http.ResponseWriter, r *http.Request) {
    mu.RLock()
    defer mu.RUnlock()
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(users)
}

// CreateUser crea un nuevo usuario a partir del JSON en el cuerpo de la petición.
func CreateUser(w http.ResponseWriter, r *http.Request) {
    var newUser User
    err := json.NewDecoder(r.Body).Decode(&newUser)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    mu.Lock()
    defer mu.Unlock()
    newUser.ID = nextID
    nextID++
    users = append(users, newUser)

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(newUser)
}

// GetUser obtiene un usuario por su ID, extraído de la variable de ruta.
func GetUser(w http.ResponseWriter, r *http.Request) {
    vars := mux.Vars(r)
    id, err := strconv.Atoi(vars["id"])
    if err != nil {
        http.Error(w, "ID de usuario inválido", http.StatusBadRequest)
        return
    }

    mu.RLock()
    defer mu.RUnlock()
    for _, user := range users {
        if user.ID == id {
            w.Header().Set("Content-Type", "application/json")
            json.NewEncoder(w).Encode(user)
            return
        }
    }
    http.Error(w, "Usuario no encontrado", http.StatusNotFound)
}

// UpdateUser actualiza un usuario existente.
func UpdateUser(w http.ResponseWriter, r *http.Request) {
    vars := mux.Vars(r)
    id, err := strconv.Atoi(vars["id"])
    if err != nil {
        http.Error(w, "ID de usuario inválido", http.StatusBadRequest)
        return
    }

    var updatedUser User
    err = json.NewDecoder(r.Body).Decode(&updatedUser)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    mu.Lock()
    defer mu.Unlock()
    for i, user := range users {
        if user.ID == id {
            updatedUser.ID = id // Aseguramos que el ID no cambie.
            users[i] = updatedUser
            w.Header().Set("Content-Type", "application/json")
            json.NewEncoder(w).Encode(updatedUser)
            return
        }
    }
    http.Error(w, "Usuario no encontrado", http.StatusNotFound)
}

// DeleteUser elimina un usuario por su ID.
func DeleteUser(w http.ResponseWriter, r *http.Request) {
    vars := mux.Vars(r)
    id, err := strconv.Atoi(vars["id"])
    if err != nil {
        http.Error(w, "ID de usuario inválido", http.StatusBadRequest)
        return
    }

    mu.Lock()
    defer mu.Unlock()
    for i, user := range users {
        if user.ID == id {
            // Elimina el usuario de la slice.
            users = append(users[:i], users[i+1:]...)
            w.WriteHeader(http.StatusNoContent) // 204 No Content es apropiado para DELETE exitoso.
            return
        }
    }
    http.Error(w, "Usuario no encontrado", http.StatusNotFound)
}

Este código implementa las cinco operaciones fundamentales. Observa el uso de mux.Vars(r) para acceder a las variables de la ruta (como `{id}`) y cómo cada manejador establece el header `Content-Type: application/json`. La gestión de la concurrencia se realiza con un sync.RWMutex, crucial para evitar condiciones de carrera ya que nuestro servidor web maneja múltiples peticiones simultáneamente de forma inherente.

Tip Importante: Siempre establece los headers HTTP, especialmente `Content-Type`, antes de escribir el cuerpo de la respuesta. Una vez que escribes en el `ResponseWriter`, los headers se envían al cliente y no pueden modificarse.

Errores Comunes y Cómo Evitarlos

1. No Validar la Entrada: Aceptar cualquier dato del cuerpo de la petición o de la ruta sin validación es una puerta abierta a errores y vulnerabilidades. Cómo evitarlo: Siempre valida que el `id` de la ruta sea un número convertible, que los campos requeridos en el JSON del cuerpo no estén vacíos, y que los tipos de datos sean los esperados. Usa librerías de validación para estructuras más complejas.

2. Olvidar la Gestión de Concurrencia: Go es concurrente por naturaleza. Si múltiples peticiones modifican la slice `users` simultáneamente sin protección, se producirán condiciones de carrera y corrupción de datos. Cómo evitarlo: Usa mecanismos de sincronización como sync.Mutex o sync.RWMutex (este último es más eficiente cuando hay muchas lecturas) para proteger el acceso a cualquier recurso compartido, como nuestra slice en memoria.

3. Mal Manejo de los Códigos de Estado HTTP: Responder siempre con `200 OK` o `500 Internal Server Error` sin matizar hace que la API sea difícil de consumir. Cómo evitarlo: Aprende y usa los códigos de estado HTTP correctamente: `201 Created` para POST exitoso, `204 No Content` para DELETE exitoso, `400 Bad Request` para error del cliente, `404 Not Found` para recursos inexistentes, y `500` solo para errores inesperados del servidor.

4. No Cerrar el Cuerpo de la Petición (Request Body): El cuerpo de `http.Request` (`r.Body`) es un `io.ReadCloser` que debe cerrarse para liberar recursos. Cómo evitarlo: En Go moderno, al decodificar el cuerpo con `json.NewDecoder(r.Body).Decode()`, el decoder se encarga de leer hasta el final. Sin embargo, si lees el cuerpo de otras formas (como con `ioutil.ReadAll`), es tu responsabilidad cerrarlo con `defer r.Body.Close()`.

5. Serializar Errores en Formato Incorrecto: Cuando usas `http.Error`, envías texto plano. Para una API REST, es mejor devolver errores también en JSON para que el cliente pueda parsearlos de manera estructurada. Cómo evitarlo: Crea una estructura para errores (ej., `{"error": "mensaje"}`) y, antes de escribir la respuesta, establece el header `Content-Type: application/json` y el código de estado, luego codifica tu estructura de error.