Validação com go-playground/validator

encoding/json mapeia bytes para tipos Go; ele não impõe regras de negócios.

github.com/go-playground/validator/v10 (verifique a versão na compilação) lê as tags de struct validate e retorna erros em nível de campo adequados para respostas HTTP 400.

Resumo

Decodifique o JSON primeiro, depois chame validator.Struct na struct populada.

As tags expressam restrições comuns (required, email, gte, oneof) e validadores personalizados estendem o motor para regras específicas do domínio.

A validação permanece separada da serialização para que a mesma struct possa ser usada em ambos os sentidos para JSON sem incorporar políticas no formato de transmissão.

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 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 para detalhes do problema JSON
}

Quando usar isso:

• Manipuladores HTTP precisam de validação de entrada consistente após a vinculação JSON.
• Você deseja regras declarativas ao lado das tags json para revisabilidade.
• Múltiplos transportes (JSON, formulários) compartilham uma única struct.

Exemplo de Trabalho

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 falhou em %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))
}

O que isso demonstra:

• A validação é executada após a decodificação JSON, não durante.
• validator.ValidationErrors expõe metadados de campo, tag e parâmetro.
• omitempty ignora regras quando o campo é zero.
• Múltiplas regras de tag são encadeadas com vírgulas.

Mergulho Profundo

Tags Comuns

A lista completa de tags está na documentação upstream (verifique a versão na compilação).

Validadores Personalizados

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

Use tags personalizadas para regras de domínio que são estranhas como regex.

Mantenha os validadores puros e rápidos; eles rodam por requisição.

Fluxo do Manipulador HTTP

1. Limite o tamanho do corpo com http.MaxBytesReader.
2. json.Decoder com DisallowUnknownFields opcional.
3. validate.Struct.
4. Mapeie erros para códigos de API estáveis (não vaze caminhos de campo internos em APIs públicas se a política exigir nomes amigáveis).

gin oferece tags binding que envolvem o validador; echo tem vinculadores semelhantes.

Você ainda pode usar o validador diretamente para código não framework.

Traduzir Erros

validator.ValidationErrors pode alimentar en_translations ou tradutores personalizados para mensagens de usuário final.

Registre detalhes técnicos no lado do servidor; retorne mensagens seguras no lado do cliente.

Notas Go

// validate:"-" ignora um campo inteiramente (timestamps definidos pelo servidor)
// Use ponteiros para que required possa distinguir ausente vs zero para números

Combine com Tags de Struct para JSON, DB e Validação para alinhamento de tags.

Armadilhas

• Esperando validação no Marshal - As tags são inertes até que Struct seja executado. Correção: valide explicitamente nos manipuladores.
• required em zero de int - 0 falha em required para inteiros. Correção: use ponteiros para números opcionais ou remova required quando 0 for válido.
• email não é perfeito - A tag verifica o formato, não a entregabilidade. Correção: adicione fluxos de confirmação para contas reais.
• Structs aninhadas - Deve-se chamar Struct na raiz; structs internas precisam de tags validate em campos aninhados. Correção: use dive para slices de DTOs aninhados.
• Corrida no validator.New por requisição - Criar o motor a cada requisição é lento. Correção: reutilize uma instância validate em nível de pacote; registre validadores personalizados em init.
• Regras diferentes por endpoint - A mesma struct usada para criar vs patch pode precisar de DTOs separados. Correção: divida os tipos em vez de sobrecarregar as tags.

Alternativas

FAQs

Relacionados

• Tags de Struct para JSON, DB e Validação - tags de validação ao lado de json/db
• Noções Básicas de Serialização - decodificar antes de validar
• Evolução de Esquema e Tratamento de Campos Desconhecidos - campos opcionais vs obrigatórios
• Serialização Personalizada do encoding/json - tipos personalizados com validação
• Melhores Práticas de Serialização - validação na lista de verificação do manipulador

Versões de 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).