Manejo de Solicitudes POST JSON en Go: 5 Errores Fatales y Cómo Evitarlos

Manejo de Solicitudes POST JSON en Go: por qué incluso los desarrolladores experimentados caen en trampas

¿Alguna vez has escrito un servidor en Go que deba aceptar JSON a través de una solicitud POST y de repente obtuviste una estructura vacía o un error fatal? Si es así, no estás solo. La pregunta "Handling JSON Post Request in Go" en Stack Overflow ha acumulado decenas de miles de visitas y cientos de respuestas. Es un verdadero "punto doloroso" de la comunidad.

En este artículo no solo analizaremos cómo procesar correctamente las solicitudes POST JSON. Revisaremos los principales errores en los que tropiezan tanto principiantes como profesionales. Aprenderás cómo evitar errores típicos, escribir código limpio y no perder horas en depuración. ¡Vamos allá!

¿Por qué JSON y Go son amor a primera vista?

Go (o Golang) fue creado para servicios web modernos. El paquete integrado encoding/json es una herramienta poderosa. Pero, como cualquier herramienta poderosa, requiere un manejo adecuado. El problema más común es la falta de coincidencia entre el JSON que envía el cliente y la estructura que espera el servidor.

Comencemos con lo básico: la estructura correcta del manejador.

Error n.º 1: Olvidar cerrar el cuerpo de la solicitud

Lo primero que debes hacer en cualquier manejador POST es cerrar obligatoriamente el cuerpo de la solicitud. Esto no es solo una buena práctica, es una garantía de que tu servidor no tendrá fugas de memoria.

package main\n\nimport (\n    "encoding/json"\n    "net/http"\n)\n\ntype User struct {\n    Name  string `json:"name"`\n    Email string `json:"email"`\n}\n\nfunc handler(w http.ResponseWriter, r *http.Request) {\n    // IMPORTANTE: cerramos el Body\n    defer r.Body.Close()\n\n    // ... resto del código\n}

Muchos principiantes omiten esta línea y el servidor comienza a "consumir" memoria. Siempre usa defer r.Body.Close() inmediatamente después de recibir la solicitud.

Error n.º 2: Ignorar la verificación del método de solicitud

Tu manejador debe verificar explícitamente que se recibió un POST, no un GET o PUT. De lo contrario, corres el riesgo de obtener un panic o un comportamiento extraño.

func handler(w http.ResponseWriter, r *http.Request) {\n    defer r.Body.Close()\n\n    if r.Method != http.MethodPost {\n        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)\n        return\n    }\n\n    // ... luego trabajamos con JSON\n}

Esta simple regla te salvará de muchos dolores de cabeza. Siempre verifica el método: es la higiene básica del código.

Error n.º 3: Usar un decodificador JSON no estricto

Por defecto, json.Decoder en Go no lanza un error si el JSON tiene campos adicionales que no están descritos en tu estructura. Esto puede provocar que "tragues" datos no válidos.

La receta para solucionarlo es usar json.Decoder con la opción DisallowUnknownFields:

func handler(w http.ResponseWriter, r *http.Request) {\n    defer r.Body.Close()\n\n    var user User\n\n    decoder := json.NewDecoder(r.Body)\n    // Activamos el modo estricto\n    decoder.DisallowUnknownFields()\n\n    err := decoder.Decode(&user)\n    if err != nil {\n        http.Error(w, "Invalid JSON: "+err.Error(), http.StatusBadRequest)\n        return\n    }\n\n    // Si el JSON tenía campos adicionales, obtendremos un error\n    // Esto es una protección contra errores tipográficos accidentales en la API\n\n    w.WriteHeader(http.StatusOK)\n    json.NewEncoder(w).Encode(user)\n}

Este enfoque es especialmente útil cuando desarrollas una API pública. Los clientes te agradecerán los errores claros.

Error n.º 4: No verificar que el JSON no esté vacío

Imagina: el cliente envía un cuerpo de solicitud vacío. Tu código decodificará sin problemas un JSON vacío {} y creará una estructura con valores cero. Esto puede no ser lo que esperas.

La mejor práctica es verificar que el cuerpo no esté vacío y que todos los campos obligatorios estén completos:

func hand