Etiquetas de Struct para JSON, BD y Validación

Los structs de producción a menudo llevan tres espacios de nombres de etiquetas en un solo campo: json para APIs, db o claves específicas de ORM para almacenamiento y validate para reglas de entrada.

Una nomenclatura consistente entre las etiquetas mantiene alineados los serializadores, los escáneres SQL y los validadores sin capas de DTO duplicadas.

Resumen

Las etiquetas de struct son metadatos de cadena adjuntos a los campos, leídos mediante reflexión en tiempo de ejecución.

Cada biblioteca analiza su propia clave (json, db, validate, xml, yaml, etc.).

Un solo struct puede servir a las capas HTTP y de base de datos cuando las etiquetas coinciden en el significado del campo pero difieren en los nombres de cable/columna.

Receta

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

type User struct {
    ID        int64     `json:"id" db:"id" validate:"required"`
    Email     string    `json:"email" db:"email" validate:"required,email"`
    Nickname  *string   `json:"nickname,omitempty" db:"nickname" validate:"omitempty,min=2,max=32"`
    CreatedAt time.Time `json:"created_at" db:"created_at" validate:"-"`
    Internal  string    `json:"-" db:"internal_note" validate:"-"`
}

Cuándo usar esto:

• Un modelo de dominio se mapea a respuestas JSON y filas SQL.
• Los validadores se ejecutan inmediatamente después de la decodificación JSON en los manejadores.
• Quieres definiciones de campo que se puedan buscar con grep en la revisión de código.

Ejemplo de Trabajo

package main
 
import (
    "encoding/json"
    "fmt"
    "time"
)
 
type Product struct {
    SKU       string    `json:"sku" db:"sku" validate:"required,alphanum"`
    Title     string    `json:"title" db:"title" validate:"required,min=3,max=120"`
    PriceCents int64    `json:"price_cents" db:"price_cents" validate:"gte=0"`
    Active    bool      `json:"active" db:"is_active" validate:"-"`
    UpdatedAt time.Time `json:"updated_at" db:"updated_at" validate:"-"`
}
 
func main() {
    p := Product{
        SKU:        "ABC123",
        Title:      "Wrench",
        PriceCents: 1299,
        Active:     true,
        UpdatedAt:  time.Now().UTC(),
    }
    b, _ := json.Marshal(p)
    fmt.Println(string(b))
 
    // La etiqueta db es ignorada por encoding/json; sqlx/jmoiron/sql usarían db:"sku" en Scan
    // Las etiquetas validate son consumidas por go-playground/validator después de Unmarshal
}

Lo que esto demuestra:

• JSON usa claves snake_case mientras que los campos de Go permanecen con el idiomático PascalCase.
• Las etiquetas db nombran columnas para sqlx, scany o escáneres similares.
• Las etiquetas validate expresan reglas separadas de la serialización.
• json:"-" oculta campos de la salida de la API mientras que db aún puede persistirlos.

Inmersión Profunda

Gramática de Etiquetas

Las etiquetas son cadenas entre comillas invertidas: `key:"value" other:"value"`.

Las comas dentro de un valor suelen ser opciones: validate:"omitempty,min=1".

Las claves desconocidas son ignoradas por cada biblioteca.

Claves de Etiqueta Comunes

Los ORM como GORM usan sus propias etiquetas de struct (gorm:"column:...") - elige un estilo de persistencia por proyecto.

Convenciones de Nomenclatura

Documenta excepciones (columnas heredadas, JSON camelCase) en ADRs.

DTOs Múltiples vs. Struct Único

Comienza con un solo struct para servicios pequeños; divide cuando el versionado de la API diverja de las tablas.

Notas de Go

// Lint: mantener los nombres json y db alineados a menos que el esquema heredado difiera
// validate:"-" omite la validación para timestamps establecidos por el servidor

Los verificadores de etiquetas de golangci-lint (cuando están habilitados) marcan nombres de campos JSON que no coinciden con los nombres de campos de Go.

Trampas

• json ignorado en campos no exportados - Las etiquetas en campos en minúscula no hacen nada para encoding/json. Solución: exporta los campos de la API o usa marshaler personalizados.
• validate nunca se ejecuta automáticamente - Las etiquetas son inertes hasta que llamas a validator.Struct. Solución: valida en los manejadores después de Unmarshal.
• etiquetas db sin la biblioteca correcta - database/sql por sí solo ignora las etiquetas db. Solución: usa sqlx/scany o listas de columnas explícitas.
• omitempty en punteros vs valores - Los enteros cero siempre se codifican a menos que sea omitempty; los punteros nil se omiten. Solución: modela números opcionales como punteros cuando 0 sea significativo.
• Desviación de etiquetas en migraciones - Renombrar una columna sin actualizar las etiquetas db causa escaneos NULL silenciosos. Solución: pruebas de integración para repositorios.
• Claves JSON conflictivas - Los structs incrustados pueden producir claves JSON duplicadas. Solución: renombra etiquetas o aplana con marshaler personalizados.

Alternativas

Preguntas Frecuentes

Relacionados

• Fundamentos de Serialización - Fundamentos de la etiqueta json
• Serialización Personalizada de encoding/json - cuando las etiquetas no son suficientes
• Validación con go-playground/validator - referencia de etiquetas validate
• Diseño de Esquemas de Protocol Buffers - protobuf como contrato alternativo
• Mejores Prácticas de Serialización - lista de verificación de revisión de etiquetas

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