Validação, migrate & sqlc

Três bibliotecas focadas cobrem bordas comuns da camada de dados em serviços Go: go-playground/validator para tags de struct, golang-migrate para versões de schema e sqlc para geração de código SQL type-safe.

Elas complementam database/sql sem impor um ORM completo.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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

Quando usar isso:

• Manipuladores HTTP decodificam DTOs JSON que precisam de validação em nível de campo antes da lógica de domínio
• Alterações de schema são enviadas em arquivos SQL versionados aplicados em trabalhos de CI e deploy
• Você deseja métodos de consulta tipados em tempo de compilação em vez de chamadas QueryRow baseadas em strings
• Equipes preferem SQL explícito a consultas geradas por ORM

Exemplo de Trabalho

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
    }
    // chama o serviço com DTO validado
    w.WriteHeader(http.StatusCreated)
}
 
func formatValidation(err error) string {
    // mapeia validator.ValidationErrors para JSON com escopo de campo em produção
    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"

O que isso demonstra:

• Validator é executado após o decode JSON, antes da camada de serviço
• Migrações vivem em arquivos SQL versionados, não no início do aplicativo
• sqlc lê arquivos de schema e consulta para gerar tipos e métodos Go
• Cada ferramenta tem uma função; regras de domínio ainda vivem nos serviços

Mergulho Profundo

Como Funciona

• validator usa tags de struct e reflection; registre validações personalizadas em uma instância compartilhada de validator.Validate.
• golang-migrate rastreia versões aplicadas em uma tabela de banco de dados e executa up/down SQL em ordem.
• sqlc analisa consultas SQL com parâmetros nomeados e emite structs Go que correspondem às colunas.
• Execute migrações antes que o novo código sirva tráfego; execute sqlc generate quando as consultas ou o schema mudarem.

Tags de Validação (comuns)

Disciplina de Migração

Fluxo de Trabalho do sqlc

1. Escreva SQL em queries/users.sql com anotações -- name: GetUser :one.
2. Aponte o sqlc para o schema de migração para tipos de coluna.
3. Commite o pacote internal/db gerado ou regenere em CI.
4. Repositórios chamam métodos gerados; escreva transações manualmente em Go.

Notas Go

// O binding do Gin/Echo pode envolver o validator - ainda mantenha os DTOs na borda
// database/sql continua sendo o driver de runtime; sqlc não substitui o ajuste do pool pgx

• Mapeie validator.ValidationErrors para problem+json para clientes de API.
• Mantenha as tags de validação em DTOs de transporte, não em entidades de domínio, para evitar vazamento de tags para dentro.

Armadilhas

• Validando invariantes de domínio apenas com tags - tags verificam a forma, não "usuário possui pedido". Correção: validator na borda, regras de negócio nos serviços.
• Executando migrações no boot do aplicativo - várias réplicas correm risco; falha no meio da migração é difícil de depurar. Correção: Job Kubernetes ou etapa de pipeline antes do rollout.
• Desvio de schema sqlc - consultas referenciam colunas que não estão na pasta de migração. Correção: única fonte de verdade para caminhos de schema em sqlc.yaml.
• Validator global compartilhado - registros de tags personalizadas modificam o estado global em testes. Correção: validator.New() por pacote ou helper de teste com cuidado t.Parallel.
• Migrações down puladas em produção - equipes executam apenas up; down quebrado esconde até emergência. Correção: teste down 1 em CI em bancos de dados descartáveis.
• Injeção de SQL em sqlc - sqlc parametriza; nomes de tabela dinâmicos em concatenação de strings ainda são inseguros. Correção: apenas consultas estáticas; filtros dinâmicos via construtores em lista branca.

Alternativas

FAQs

Relacionados

• Migrações com golang-migrate & goose - mergulho profundo nas ferramentas de migração
• Validação de Entrada e Tratamento Seguro de HTML/JSON - validação com foco em segurança
• GORM vs sqlx vs Raw database/sql - escolhas de acesso a dados
• Noções Básicas de Bancos de Dados - iniciantes em conexão e consulta
• Gin: APIs JSON Rápidas e Binding - conexão de validação de framework

Versões da Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).