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.
Integração com o validador
Seção intitulada “Integração com o validador”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.
Struct tags
Seção intitulada “Struct tags”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.
Validação automática
Seção intitulada “Validação automática”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 |
Erros de validação
Seção intitulada “Erros de validação”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"`}Nomes de campos nos erros
Seção intitulada “Nomes de campos nos erros”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.
Validação durante o binding
Seção intitulada “Validação durante o binding”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)}