Tags de Struct para JSON, Banco de Dados e Validação

Structs de produção frequentemente carregam três namespaces de tags em um único campo: json para APIs, db ou chaves específicas de ORM para armazenamento e validate para regras de entrada.

Nomes consistentes entre as tags mantêm serializadores, scanners SQL e validadores alinhados sem camadas DTO duplicadas.

Resumo

Tags de struct são metadados de string anexados a campos, lidos via reflection em tempo de execução.

Cada biblioteca analisa sua própria chave (json, db, validate, xml, yaml, etc.).

Uma única struct pode servir às camadas HTTP e de banco de dados quando as tags concordam sobre o significado do campo, mas diferem nos nomes de fio/coluna.

Receita

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

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:"-"`
}

Quando usar isso:

• Um modelo de domínio mapeia para respostas JSON e linhas SQL.
• Validadores são executados imediatamente após a decodificação JSON nos manipuladores.
• Você deseja definições de campo "grep-friendly" em revisões de código.

Exemplo de Trabalho

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))
 
    // A tag db é ignorada pelo encoding/json; sqlx/jmoiron/sql usaria db:"sku" no Scan
    // As tags validate são consumidas pelo go-playground/validator após o Unmarshal
}

O que isso demonstra:

• JSON usa chaves snake_case enquanto os campos Go permanecem no estilo PascalCase idiomático.
• Tags db nomeiam colunas para sqlx, scany ou scanners semelhantes.
• Tags validate expressam regras separadas da serialização.
• json:"-" oculta campos da saída da API enquanto db ainda pode persistí-los.

Mergulho Profundo

Gramática de Tags

Tags são strings entre crases: `chave:"valor" outra:"valor"`.

Vírgulas dentro de um valor geralmente são opções: validate:"omitempty,min=1".

Chaves desconhecidas são ignoradas por cada biblioteca.

Chaves de Tag Comuns

ORMs como GORM usam suas próprias tags de struct (gorm:"column:...") - escolha um estilo de persistência por projeto.

Convenções de Nomenclatura

Documente exceções (colunas legadas, camelCase JSON) em ADRs.

DTOs Múltiplos vs. Struct Única

Comece com struct única para serviços pequenos; divida quando a versão da API divergir das tabelas.

Notas Go

// Lint: mantenha os nomes json e db alinhados, a menos que o esquema legado difira
// validate:"-" ignora a validação para timestamps definidos pelo servidor

Verificadores de tags do golangci-lint (quando habilitados) sinalizam nomes de campos JSON incompatíveis com nomes de campos Go.

Armadilhas

• json ignorado em campos não exportados - Tags em campos minúsculos não fazem nada para encoding/json. Correção: exporte campos de API ou use marshaler personalizados.
• validate nunca é executado automaticamente - As tags são inertes até que você chame validator.Struct. Correção: valide nos manipuladores após Unmarshal.
• tags db sem a biblioteca correta - database/sql sozinho ignora tags db. Correção: use sqlx/scany ou listas de colunas explícitas.
• omitempty em ponteiros vs. valores - Inteiros zero sempre codificam, a menos que omitempty; ponteiros nil omitem. Correção: modele números opcionais como ponteiros quando 0 for significativo.
• Derivação de tags em migrações - Renomear uma coluna sem atualizar as tags db causa scans NULL silenciosos. Correção: testes de integração para repositórios.
• Conflitos de chaves json - Structs incorporadas podem produzir chaves JSON duplicadas. Correção: renomeie tags ou achate com marshaler personalizados.

Alternativas

FAQs

Relacionados

• Fundamentos de Serialização - Fundamentos da tag json
• Serialização Personalizada com encoding/json - quando tags não são suficientes
• Validação com go-playground/validator - referência de tag validate
• Design de Esquema Protocol Buffers - protobuf como contrato alternativo
• Melhores Práticas de Serialização - lista de verificação de revisão de tags

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