Pular para o conteúdo

Validação

O Kori integra o go-playground/validator e executa a validação automaticamente como parte do binding. Não há uma etapa de validação separada.

O Kori inicializa uma instância compartilhada de *validator.Validate com WithRequiredStructEnabled, o que faz a tag required se aplicar a structs e campos não-ponteiro de forma consistente.

O validador é compartilhado por todas as chamadas de binding e inicializado uma única vez. Não é necessário configurá-lo ou instanciá-lo manualmente.

Adicione tags validate aos campos para declarar restrições:

type CreateUserInput struct {
Name string `json:"name" validate:"required,min=2,max=100"`
Email string `json:"email" validate:"required,email"`
Age int `json:"age" validate:"required,gte=0,lte=130"`
Role string `json:"role" validate:"required,oneof=admin editor viewer"`
}

Qualquer tag suportada pelo go-playground/validator é aceita. Tags comuns:

Tag Significado
required Campo deve estar presente e não-zero
omitempty Pula a validação se o campo for zero
min=N Comprimento mínimo (string) ou valor mínimo (número)
max=N Comprimento máximo (string) ou valor máximo (número)
gte=N Maior ou igual a N
lte=N Menor ou igual a N
gt=N Maior que N
lt=N Menor que N
email Deve ser um endereço de e-mail válido
url Deve ser uma URL válida
uuid4 Deve ser um UUID v4 válido
uuid Deve ser um UUID válido (qualquer versão)
oneof=a b c Deve ser um dos valores listados
len=N Deve ter exatamente N caracteres

As tags acima produzem uma message legível na resposta de erro. Qualquer outra tag do validator continua funcionando, mas sua message cai no erro cru do go-playground/validator.

Toda função de binding executa a validação após a decodificação. Nenhuma chamada explícita é necessária:

func createUser(w http.ResponseWriter, r *http.Request) error {
var input CreateUserInput
if err := kori.BindJSON(r, &input); err != nil {
return err // 400 em JSON inválido, 422 em falha de validação
}
// input é válido aqui
return kori.JSON(w, http.StatusCreated, input)
}

As funções de binding que validam são:

Função Decodifica
kori.BindJSON(r, dst) Corpo da requisição (JSON)
kori.BindQuery(r, dst) Parâmetros de query da URL
kori.BindPath(r, dst) Parâmetros de caminho do Chi
kori.BindHeader(r, dst) Headers HTTP
kori.BindForm(r, dst) Valores de formulário (application/x-www-form-urlencoded)
kori.BindMultipart(r, dst) Dados de formulário multipart
kori.Bind(r, dst) Path + query + headers combinados

Quando a validação falha, o Kori retorna 422 Unprocessable Entity com um corpo estruturado:

{
"message": "validation failed",
"details": [
{
"field": "email",
"tag": "email",
"message": "email must be a valid email address"
},
{
"field": "name",
"tag": "min",
"param": "2",
"message": "name must be at least 2"
}
]
}

Cada entrada corresponde a um ValidationDetail:

type ValidationDetail struct {
Field string `json:"field"`
Tag string `json:"tag"`
Param string `json:"param,omitempty"`
Message string `json:"message"`
}

O Kori registra uma função de resolução de nomes de tag no validador. Ao reportar erros, os nomes dos campos são resolvidos a partir da tag de binding da struct — não do nome do campo Go:

type Query struct {
PageSize int `query:"page_size" validate:"min=1,max=100"`
}

Uma falha de validação em PageSize reporta "field": "page_size", não "field": "PageSize". O resolvedor verifica as tags nesta ordem: json, query, path, header, form.

Binding e validação compartilham a mesma struct. As tags de decodificação (json, query, path, header, form) e as tags de validação (validate) ficam no mesmo campo:

type ListTodosParams struct {
Completed *bool `query:"completed"`
Search string `query:"search" validate:"omitempty,max=100"`
Page int `query:"page" validate:"omitempty,min=1"`
PageSize int `query:"page_size" validate:"omitempty,min=1,max=100"`
}
func listTodos(w http.ResponseWriter, r *http.Request) error {
var q ListTodosParams
if err := kori.BindQuery(r, &q); err != nil {
return err
}
// q está decodificado e validado
return kori.JSON(w, http.StatusOK, results)
}

Parâmetros de caminho funcionam da mesma forma:

type PathID struct {
ID int `path:"id" validate:"required,min=1"`
}
func getTodo(w http.ResponseWriter, r *http.Request) error {
var p PathID
if err := kori.BindPath(r, &p); err != nil {
return err
}
// p.ID é um int, decodificado da URL e validado
return kori.JSON(w, http.StatusOK, todo)
}