Validación con go-playground/validator

encoding/json mapea bytes a tipos de Go; no impone reglas de negocio.

github.com/go-playground/validator/v10 (verifica la versión en el momento de la compilación) lee las etiquetas de struct validate y devuelve errores a nivel de campo adecuados para respuestas HTTP 400.

Resumen

Decodifica JSON primero, luego llama a validator.Struct en el struct poblado.

Las etiquetas expresan restricciones comunes (required, email, gte, oneof) y los validadores personalizados extienden el motor para reglas específicas del dominio.

La validación se mantiene separada de la serialización para que el mismo struct pueda viajar de ida y vuelta a JSON sin incorporar políticas en el formato de transmisión.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

import "github.com/go-playground/validator/v10"
 
var validate = validator.New()
 
type CreateOrder struct {
    SKU string `json:"sku" validate:"required,alphanum,min=3,max=32"`
    Qty int    `json:"qty" validate:"required,gte=1,lte=1000"`
}
 
if err := json.NewDecoder(r.Body).Decode(&req); err != nil { /* 400 */ }
if err := validate.Struct(req); err != nil {
    verrs := err.(validator.ValidationErrors)
    // mapear a detalles de problema JSON
}

Cuándo usar esto:

• Los manejadores HTTP necesitan validación de entrada consistente después de la vinculación JSON.
• Quieres reglas declarativas junto a las etiquetas json para facilitar la revisión.
• Múltiples transportes (JSON, formularios) comparten un mismo struct.

Ejemplo de Trabajo

package main
 
import (
    "encoding/json"
    "fmt"
    "strings"
 
    "github.com/go-playground/validator/v10"
)
 
type Signup struct {
    Email       string `json:"email" validate:"required,email"`
    Age         int    `json:"age" validate:"gte=13,lte=120"`
    Country     string `json:"country" validate:"required,len=2,alpha"`
    Referral    string `json:"referral" validate:"omitempty,alphanum"`
}
 
func formatErrors(err error) string {
    var b strings.Builder
    for _, fe := range err.(validator.ValidationErrors) {
        fmt.Fprintf(&b, "%s failed %s; ", fe.Field(), fe.Tag())
    }
    return strings.TrimSuffix(b.String(), "; ")
}
 
func main() {
    validate := validator.New()
 
    raw := []byte(`{"email":"not-an-email","age":10,"country":"USA"}`)
    var s Signup
    _ = json.Unmarshal(raw, &s)
 
    if err := validate.Struct(s); err != nil {
        fmt.Println(formatErrors(err))
    }
 
    good := Signup{Email: "ada@example.com", Age: 30, Country: "US"}
    fmt.Println(validate.Struct(good))
}

Lo que esto demuestra:

• La validación se ejecuta después de la decodificación JSON, no durante.
• validator.ValidationErrors expone metadatos de campo, etiqueta y parámetro.
• omitempty omite las reglas cuando el campo está en cero.
• Múltiples reglas de etiqueta se encadenan con comas.

Profundización

Etiquetas Comunes

La lista completa de etiquetas se encuentra en la documentación upstream (verifica la versión en el momento de la compilación).

Validadores Personalizados

validate := validator.New()
_ = validate.RegisterValidation("sku", func(fl validator.FieldLevel) bool {
    s := fl.Field().String()
    return strings.HasPrefix(s, "SKU-")
})

Usa etiquetas personalizadas para reglas de dominio que son incómodas como expresiones regulares.

Mantén los validadores puros y rápidos; se ejecutan por solicitud.

Flujo del Manejador HTTP

1. Limita el tamaño del cuerpo con http.MaxBytesReader.
2. json.Decoder con DisallowUnknownFields opcional.
3. validate.Struct.
4. Mapea errores a códigos de API estables (no filtres rutas de campo internas en APIs públicas si la política requiere nombres amigables).

gin ofrece etiquetas binding que envuelven al validador; echo tiene enlazadores similares.

Aún puedes usar el validador directamente para código que no sea de framework.

Traducir Errores

validator.ValidationErrors puede alimentar en_translations o traductores personalizados para mensajes de usuario final.

Registra detalles técnicos en el servidor; devuelve mensajes seguros en el cliente.

Notas de Go

// validate:"-" omite un campo por completo (marcas de tiempo establecidas por el servidor)
// Usa punteros para que required pueda distinguir entre ausente y cero para números

Empareja con Etiquetas de Struct para JSON, DB y Validación para alinear etiquetas.

Trampas Comunes

• Esperar validación en Marshal - Las etiquetas son inertes hasta que se ejecuta Struct. Solución: valida explícitamente en los manejadores.
• required en cero entero - 0 falla required para enteros. Solución: usa punteros para números opcionales o elimina required cuando 0 sea válido.
• email no es perfecto - La etiqueta verifica el formato, no la entregabilidad. Solución: agrega flujos de confirmación para cuentas reales.
• Structs anidados - Debes llamar a Struct en la raíz; los structs internos necesitan etiquetas validate en los campos anidados. Solución: usa dive para arreglos de DTOs anidados.
• Carrera en validator.New por solicitud - Crear el motor en cada solicitud es lento. Solución: reutiliza una instancia validate a nivel de paquete; registra validadores personalizados en init.
• Reglas diferentes por endpoint - El mismo struct usado para crear vs. parchear puede necesitar DTOs separados. Solución: divide los tipos en lugar de sobrecargar las etiquetas.

Alternativas

Preguntas Frecuentes

Relacionado

• Etiquetas de Struct para JSON, DB y Validación - valida etiquetas junto a json/db
• Conceptos Básicos de Serialización - decodifica antes de validar
• Evolución del Esquema y Manejo de Campos Desconocidos - campos opcionales vs. requeridos
• Serialización Personalizada de encoding/json - tipos personalizados con validación
• Mejores Prácticas de Serialización - lista de verificación de validación en el manejador

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de Green Tea GC, go fix modernizers - verifica el parche en el momento de la compilación), chi (última versión - verifica en el momento de la compilación), gin (última versión - verifica en el momento de la compilación), echo (última versión - verifica en el momento de la compilación), google.golang.org/grpc (última versión - verifica en el momento de la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en el momento de la compilación), kubebuilder (última versión - verifica en el momento de la compilación), tinygo (última versión - verifica objetivos de placa en el momento de la compilación), wazero (última versión - verifica en el momento de la compilación) y golangci-lint (última versión - verifica el conjunto de linters en el momento de la compilación).