Validación y serialización de datos con structs y JSON

Introducción: El Pilar de la Confiabilidad en APIs

En el desarrollo de APIs REST, especialmente aquellas diseñadas para alto rendimiento, la integridad de los datos no es una característica opcional, es el cimiento. Cada petición HTTP que llega a nuestro microservicio trae consigo un potencial de caos: datos malformados, tipos incorrectos, campos obligatorios ausentes o información sensible expuesta. La validación y serialización son los dos guardianes que se interponen entre ese caos y la lógica de negocio de nuestra aplicación.

Go, con su sistema de tipos estático y su filosofía de simplicidad, ofrece herramientas poderosas para esta tarea. A través del uso de structs, tags y la biblioteca estándar encoding/json, podemos definir contratos de datos claros y explícitos. Esta lección se centrará en cómo estructurar, validar y transformar los datos de entrada (JSON a struct) y de salida (struct a JSON) de manera eficiente, segura y mantenible, utilizando gorilla/mux como nuestro enrutador. Dominar este flujo es crucial para construir APIs que no solo sean rápidas, sino también robustas y predecibles.

Concepto Clave: El Contrato de Datos

Imagina que tu API es un servicio de mensajería de alta seguridad. Cuando alguien quiere enviar un paquete (hacer una petición POST), debe usar una caja estandarizada (el formato JSON) y llenar una etiqueta de envío con campos específicos: dirección destino (obligatoria), tipo de contenido, valor declarado, etc. Tu sistema, antes de procesar el envío, verifica que la caja sea del tamaño correcto (validación de tipo), que todos los campos obligatorios de la etiqueta estén llenos (validación de presencia) y que el código postal tenga el formato adecuado (validación de formato). La struct en Go es la plantilla para esa etiqueta de envío. Define exactamente qué campos esperas, de qué tipo son y cuáles son las reglas.

La serialización es el proceso de empaquetar y desempacar. Unmarshaling (deserialización) es cuando tomas el JSON entrante (la caja cerrada) y lo "desempacas" en una instancia de tu struct, verificando que todo encaje. Marshaling (serialización) es el proceso inverso: tomas la data de tu struct (el objeto en memoria) y la "empaquetas" en un JSON para enviarlo como respuesta. Los tags de struct, como `json:"field_name"` o `validate:"required"`, son las instrucciones detalladas que le das al sistema sobre cómo debe realizarse este empaquetado y qué validaciones extra aplicar.

Tip del Instructor: Piensa en tu struct como la fuente única de la verdad para un recurso de tu API. Toda validación, transformación y documentación (a través de comentarios) debe emanar de esta definición. Esto reduce la duplicación y los errores.

Cómo Funciona en la Práctica: Flujo de una Petición

Vamos a seguir el viaje de una petición POST para crear un nuevo usuario. Primero, el cliente envía un cuerpo JSON. Gorilla/mux nos da acceso al cuerpo de la petición a través de http.Request.Body. Nuestro primer paso es leer este cuerpo y usar json.NewDecoder().Decode(&miStruct) para intentar deserializarlo. Si el JSON tiene un campo "age" y nuestra struct lo define como int, la biblioteca json intentará la conversión automáticamente. Si falla (por ejemplo, "age": "veinticinco"), el Decoder devolverá un error que debemos manejar inmediatamente con un código de estado HTTP 400 (Bad Request).

Sin embargo, la validación de tipos básica no es suficiente. ¿Qué pasa si el campo "email" tiene un string pero no tiene formato de email? Aquí es donde entran bibliotecas de validación externas como go-playground/validator. Después del unmarshal exitoso, pasamos nuestra struct poblada a un validador que verifica reglas complejas definidas en los tags. Si la validación falla, respondemos con un 422 (Unprocessable Entity) o 400, detallando los errores. Solo después de que todas las validaciones pasen, el dato llega a la capa de negocio o de base de datos. Para la respuesta, hacemos el proceso inverso: tomamos la struct (quizá enriquecida con un ID y fechas de creación) y usamos json.NewEncoder(w).Encode(data) para serializarla a JSON y escribirla en el http.ResponseWriter.

Código en Acción: Implementación Completa

El siguiente ejemplo muestra un manejador HTTP completo para crear un producto, incluyendo definición de struct, validación, manejo de errores y respuestas apropiadas. Utilizamos el enrutador gorilla/mux y el validador go-playground/validator/v10.

package main

import (
    "encoding/json"
    "net/http"
    "time"

    "github.com/go-playground/validator/v10"
    "github.com/gorilla/mux"
)

// Product define la estructura de datos para un producto con tags para JSON y validación.
type Product struct {
    ID          string    `json:"id,omitempty"` // omitempty omite el campo si está vacío en la respuesta
    Name        string    `json:"name" validate:"required,min=3,max=100"`
    Description string    `json:"description,omitempty" validate:"max=500"`
    Price       float64   `json:"price" validate:"required,gt=0"`
    SKU         string    `json:"sku" validate:"required,alphanum"`
    Category    string    `json:"category" validate:"oneof=electronics clothing home books"`
    InStock     bool      `json:"in_stock"`
    CreatedAt   time.Time `json:"created_at,omitempty"`
    UpdatedAt   time.Time `json:"updated_at,omitempty"`
}

var validate *validator.Validate

func main() {
    validate = validator.New()
    r := mux.NewRouter()
    r.HandleFunc("/api/v1/products", createProduct).Methods("POST")
    http.ListenAndServe(":8080", r)
}

// createProduct maneja la creación de un nuevo producto.
func createProduct(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")

    var prod Product
    // 1. Deserialización (Unmarshal) del JSON del cuerpo de la petición.
    if err := json.NewDecoder(r.Body).Decode(∏); err != nil {
        http.Error(w, `{"error": "Invalid JSON format"}`, http.StatusBadRequest)
        return
    }

    // 2. Validación de reglas de negocio usando go-playground/validator.
    if err := validate.Struct(prod); err != nil {
        var validationErrors []string
        for _, err := range err.(validator.ValidationErrors) {
            validationErrors = append(validationErrors, err.Field()+": failed rule '"+err.Tag()+"'")
        }
        errorResponse := map[string]interface{}{
            "error":            "Validation failed",
            "validation_errors": validationErrors,
        }
        w.WriteHeader(http.StatusUnprocessableEntity)
        json.NewEncoder(w).Encode(errorResponse)
        return
    }

    // 3. Simulación de lógica de negocio (e.g., guardar en DB).
    // Aquí se asignarían ID y timestamps.
    prod.ID = "generated-unique-id-123"
    prod.CreatedAt = time.Now()
    prod.UpdatedAt = time.Now()

    // 4. Serialización (Marshal) y respuesta con el producto creado.
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(prod)
}

Este código demuestra el flujo completo. Nota cómo los tags validate definen reglas como required, min, oneof. El manejo de errores es granular: errores de JSON malformado devuelven 400, errores de validación de negocio devuelven 422 con detalles. Los campos omitempty en los tags JSON aseguran que no enviemos campos vacíos (como ID antes de ser creado), haciendo las respuestas más limpias.

Manejo Avanzado con Structs Anidados

Los recursos del mundo real a menudo tienen estructuras complejas. Go maneja esto perfectamente con structs anidados, y la validación y serialización funcionan de manera recursiva.

type Address struct {
    Street string `json:"street" validate:"required"`
    City   string `json:"city" validate:"required"`
    Zip    string `json:"zip" validate:"required,numeric,len=5"`
}

type Customer struct {
    ID        string    `json:"id,omitempty"`
    FirstName string    `json:"first_name" validate:"required"`
    LastName  string    `json:"last_name" validate:"required"`
    Email     string    `json:"email" validate:"required,email"`
    Active    bool      `json:"active"`
    Address   Address   `json:"address" validate:"required"` // Validación recursiva
    CreatedAt time.Time `json:"created_at,omitempty"`
}

// El validador comprobará automáticamente los campos dentro de `Address` porque tiene el tag `validate:"required"`.

Errores Comunes y Cómo Evitarlos

Al trabajar con validación y serialización, varios errores sutiles pueden introducir bugs o vulnerabilidades.

1. Ignorar los errores de Decode() o Unmarshal(): Este es el error cardinal. Siempre, sin excepción, debes verificar el error devuelto por estas operaciones. Un JSON malformado o un tipo incompatible debe rechazarse inmediatamente.

2. Exponer campos internos de la struct: Usar structs públicas sin cuidado puede filtrar datos. Usa structs anónimas o structs separadas para la entrada (request) y la salida (response). Por ejemplo, el campo PasswordHash nunca debe tener un tag json:.

// MAL: Expone el hash de la contraseña en la respuesta JSON.
type User struct {
    ID           string `json:"id"`
    Email        string `json:"email"`
    PasswordHash string `json:"password_hash"` // ¡FILTRACIÓN GRAVE!
}

// BIEN: Struct para entrada (CreateUserRequest) y otra para salida (UserResponse).
type CreateUserRequest struct {
    Email    string `json:"email" validate:"required,email"`
    Password string `json:"password" validate:"required,min=8"`
}
type UserResponse struct {
    ID    string `json:"id"`
    Email string `json:"email"`
    // No hay campo PasswordHash aquí.
}

3. No validar a nivel de negocio, solo a nivel de tipo: Que un campo sea un int no significa que sea válido (ej. una edad de -5 o 300). Complementa la validación de tipos con reglas de validador (gt=0, lte=120) o lógica personalizada.

4. Mal uso de omitempty con tipos numéricos cero: El tag omitempty omite un campo si tiene su valor cero (0 para números, false para booleanos, "" para strings). Si el valor cero es válido para tu negocio (ej. un producto puede tener precio 0 en promoción), no uses omitempty en ese campo, o usarás un puntero (*float64) para distinguir entre "no proporcionado" y "cero".

Checklist de Dominio

Antes de considerar dominada esta lección, asegúrate de poder verificar y explicar cada uno de los siguientes puntos:

• Puedo definir una struct con tags json para controlar el nombre, omisión y formato de los campos en la serialización.
• Sé integrar y usar una biblioteca de validación como go-playground/validator para imponer reglas complejas (required, email, min, max, oneof, custom) sobre los datos deserializados.
• Comprendo y aplico la diferencia entre manejar errores de sintaxis JSON (HTTP 400) y errores de validación de negocio (HTTP 422/400 con detalles).
• Utilizo structs diferentes para modelar los datos de entrada (Request) y los de salida (Response) de mis endpoints para evitar la exposición accidental de datos.
• Puedo manejar correctamente la serialización/deserialización de tipos complejos como time.Time, structs anidadas y slices.
• Sé cómo escribir middleware para gorilla/mux que centralice la deserialización y validación básica, limpiando el código de los manejadores.
• Puedo explicar el impacto del uso de omitempty y los punteros en la representación JSON de los valores cero.
• He probado mis endpoints con herramientas como curl o Postman, enviando datos malformados y verificando que los errores se manejan de manera informativa y segura.

Consejo Final: La disciplina en la validación y serialización es lo que separa una API profesional de una experimental. Invierte tiempo en diseñar tus structs y tus respuestas de error. Esta inversión se paga con creces en reducción de bugs, mejor experiencia para el cliente de la API y una base de código mucho más mantenible.