Validación, migrate y sqlc

Tres bibliotecas enfocadas cubren los bordes comunes de la capa de datos en servicios Go: go-playground/validator para etiquetas de struct, golang-migrate para versiones de esquema y sqlc para generación de código SQL tipo-seguro.

Complementan database/sql sin imponer un ORM completo.

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 CreateUser struct {
    Email string `json:"email" validate:"required,email"`
    Age   int    `json:"age" validate:"gte=18,lte=120"`
}
 
func check(in CreateUser) error {
    return validate.Struct(in)
}

migrate -path ./migrations -database "${DATABASE_URL}" up
sqlc generate

Cuándo recurrir a esto:

• Los manejadores HTTP decodifican DTOs JSON que necesitan validación a nivel de campo antes de la lógica de dominio.
• Los cambios de esquema se envían en archivos SQL versionados aplicados en trabajos de CI y despliegue.
• Quieres métodos de consulta tipados en tiempo de compilación en lugar de llamadas QueryRow basadas en cadenas.
• Los equipos prefieren SQL explícito sobre consultas generadas por ORM.

Ejemplo de Trabajo

package api
 
import (
    "context"
    "encoding/json"
    "net/http"
 
    "github.com/go-playground/validator/v10"
)
 
var validate = validator.New()
 
type createUserRequest struct {
    Email string `json:"email" validate:"required,email"`
    Name  string `json:"name" validate:"required,min=1,max=128"`
}
 
func createUser(w http.ResponseWriter, r *http.Request) {
    var in createUserRequest
    if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
        http.Error(w, "invalid json", http.StatusBadRequest)
        return
    }
    if err := validate.Struct(in); err != nil {
        http.Error(w, formatValidation(err), http.StatusBadRequest)
        return
    }
    // llama al servicio con el DTO validado
    w.WriteHeader(http.StatusCreated)
}
 
func formatValidation(err error) string {
    // mapea validator.ValidationErrors a JSON con ámbito de campo en producción
    return err.Error()
}

-- migrations/000001_create_users.up.sql
CREATE TABLE users (
    id   BIGSERIAL PRIMARY KEY,
    email TEXT NOT NULL UNIQUE,
    name  TEXT NOT NULL
);

# sqlc.yaml
version: "2"
sql:
  - engine: "postgresql"
    queries: "queries/"
    schema: "migrations/"
    gen:
      go:
        package: "db"
        out: "internal/db"

Lo que esto demuestra:

• Validator se ejecuta después de la decodificación JSON, antes de la capa de servicio.
• Las migraciones viven en archivos SQL versionados, no en el inicio de la aplicación.
• sqlc lee los archivos de esquema y consulta para generar tipos y métodos Go.
• Cada herramienta se encarga de una tarea; las reglas de dominio aún viven en los servicios.

Inmersión Profunda

Cómo Funciona

• validator usa etiquetas de struct y reflexión; registra validaciones personalizadas en una instancia compartida de validator.Validate.
• golang-migrate rastrea las versiones aplicadas en una tabla de base de datos y ejecuta up/down SQL en orden.
• sqlc analiza las consultas SQL con parámetros nombrados y emite structs Go que coinciden con las columnas.
• Ejecuta migraciones antes de que el nuevo código sirva tráfico; ejecuta sqlc generate cuando cambian las consultas o el esquema.

Etiquetas de Validación (comunes)

Disciplina de Migración

Flujo de Trabajo de sqlc

1. Escribe SQL en queries/users.sql con anotaciones -- name: GetUser :one.
2. Apunta sqlc al esquema de migración para los tipos de columna.
3. Confirma el paquete internal/db generado o regenera en CI.
4. Los repositorios llaman a los métodos generados; escriben transacciones a mano en Go.

Notas de Go

// La vinculación de Gin/Echo puede envolver a validator; aún así, mantén los DTOs en el borde.
// database/sql sigue siendo el controlador en tiempo de ejecución; sqlc no reemplaza la optimización del pool de pgx.

• Mapea validator.ValidationErrors a problem+json para clientes de API.
• Mantén las etiquetas de validación en los DTOs de transporte, no en las entidades de dominio, para evitar fugas de etiquetas hacia adentro.

Trampas

• Validar invariantes de dominio solo con etiquetas - las etiquetas verifican la forma, no "el usuario posee el pedido". Solución: validator en el borde, reglas de negocio en los servicios.
• Ejecutar migraciones al iniciar la aplicación - múltiples réplicas compiten; una migración fallida a mitad de camino es difícil de depurar. Solución: Trabajo de Kubernetes o paso de pipeline antes del despliegue.
• Desfase de esquema de sqlc - las consultas hacen referencia a columnas que no están en la carpeta de migraciones. Solución: única fuente de verdad para las rutas de esquema en sqlc.yaml.
• Validator global compartido - los registros de etiquetas personalizadas mutan el estado global en las pruebas. Solución: validator.New() por paquete o ayudante de prueba con cuidado de t.Parallel.
• Migraciones down omitidas en producción - los equipos solo ejecutan up; un down roto se oculta hasta una emergencia. Solución: prueba down 1 en CI en bases de datos desechables.
• Inyección SQL en sqlc - sqlc parametriza; los nombres de tabla dinámicos en la concatenación de cadenas siguen siendo inseguros. Solución: solo consultas estáticas; filtros dinámicos a través de constructores en lista blanca.

Alternativas

Preguntas Frecuentes

Relacionado

• Migraciones con golang-migrate & goose - inmersión profunda en herramientas de migración
• Validación de Entrada y Manejo Seguro de HTML/JSON - validación con mentalidad de seguridad
• GORM vs sqlx vs Raw database/sql - opciones de acceso a datos
• Conceptos Básicos de Bases de Datos - inicio de conexión y consulta
• Gin: APIs JSON Rápidas y Vinculación - conexión de validación de framework

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