Biblioteca validator para Go: guia completo

1. O que é e para que serve

A biblioteca validator (nome completo do pacote — github.com/go-playground/validator/v10) é uma ferramenta poderosa e flexível para validação de structs e campos individuais na linguagem Go. Ela permite descrever regras de validação de forma declarativa diretamente nas tags das structs, tornando o código limpo, legível e fácil de manter. Em vez de escrever dezenas de linhas de verificações manuais (if-else, switch), basta adicionar tags aos campos, e a biblioteca faz todo o trabalho para você.

Para que serve? Em qualquer aplicação web, API ou serviço que lida com entrada de dados do usuário, é fundamental validar os dados antes de processá-los. Um email inválido, nome vazio, idade negativa, senha muito longa — tudo isso pode causar erros de lógica, vulnerabilidades (SQL injection, XSS) ou queda do servidor. O validator resolve esse problema de forma elegante: você define as regras uma vez e depois chama a função Validate.Struct(), que verifica todos os campos automaticamente.

A biblioteca oferece dezenas de validadores embutidos (required, min, max, email, url, uuid, oneof, len e muitos outros), além de permitir a criação de validadores personalizados. É amplamente utilizada em produção, possui excelente desempenho (graças ao cache de reflexão) e é compatível com frameworks populares como Gin, Echo e Fiber. Se você programa em Go e quer evitar código repetitivo, esta biblioteca é indispensável.

2. Instalação

A instalação da biblioteca é feita da forma padrão com go get. Certifique-se de ter o Go versão 1.18 ou superior (recomendado 1.21+).

go get github.com/go-playground/validator/v10

Após executar o comando, o pacote será adicionado ao seu go.mod. Importe-o no código:

import "github.com/go-playground/validator/v10"

3. Início rápido — exemplo mínimo funcional

Vamos criar uma estrutura simples de usuário e validar seus campos. Este é um exemplo mínimo que demonstra a ideia principal.

package main

import (
    "fmt"
    "github.com/go-playground/validator/v10"
)

// User — struct com tags de validação
type User struct {
    Name  string `validate:"required,min=2,max=50"`
    Email string `validate:"required,email"`
    Age   int    `validate:"gte=0,lte=150"`
}

func main() {
    // Cria uma instância do validador
    validate := validator.New()

    // Dados de teste
    user := User{
        Name:  "A",               // Nome muito curto
        Email: "email-invalido",  // Email inválido
        Age:   -5,                // Idade negativa
    }

    // Executa a validação
    err := validate.Struct(user)
    if err != nil {
        // Percorre todos os erros
        for _, err := range err.(validator.ValidationErrors) {
            fmt.Printf("Campo: %s, Erro: %s, Valor: %v\n",
                err.Field(), err.Tag(), err.Value())
        }
    } else {
        fmt.Println("Validação concluída com sucesso!")
    }
}

Saída do programa:

Campo: Name, Erro: min, Valor: A
Campo: Email, Erro: email, Valor: email-invalido
Campo: Age, Erro: gte, Valor: -5

Como você pode ver, a biblioteca encontra automaticamente todas as violações e retorna informações estruturadas sobre cada erro.

4. Principais métodos e funções

Abaixo estão 8 métodos e funções essenciais da biblioteca. Para cada um, são fornecidos a assinatura, descrição e um exemplo prático.

4.1. validator.New()

Assinatura: func New() *Validate

O que faz: Cria uma nova instância do validador. Este é o objeto principal através do qual todas as validações são executadas. Recomenda-se criar uma única instância para toda a aplicação.