Pular para o conteúdo

Handlers

Um handler no Kori é uma função que processa uma requisição HTTP e retorna um erro.

A biblioteca padrão define um handler como uma função que escreve no ResponseWriter e não retorna nada:

func listUsers(w http.ResponseWriter, r *http.Request) {
users, err := db.All()
if err != nil {
http.Error(w, "internal server error", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK)
json.NewEncoder(w).Encode(users)
}

O tratamento de erros é manual. Todo caminho que falha exige escrever uma resposta e retornar antecipadamente. Esquecer qualquer um dos dois é um bug silencioso.

O Kori define seu próprio tipo de handler:

type Handler func(w http.ResponseWriter, r *http.Request) error

A assinatura é idêntica à de http.HandlerFunc, exceto pelo retorno error. O Kori envolve o handler internamente e intercepta qualquer erro não-nulo antes que ele chegue ao cliente.

func listUsers(w http.ResponseWriter, r *http.Request) error {
users, err := db.All()
if err != nil {
return kori.InternalServerError("could not fetch users")
}
return kori.JSON(w, http.StatusOK, users)
}

Handlers são registrados em qualquer chi.Router:

kori.GET(r, "/users", listUsers)

Quando um handler retorna um erro, o Kori o passa para o handler de erro configurado. O comportamento padrão é:

Valor retornado Resposta
nil Nenhuma ação — você já escreveu a resposta
*kori.HTTPError JSON com o status code do erro
Qualquer outro error 500 Internal Server Error

O Kori fornece construtores para os status codes mais comuns:

return kori.BadRequest("invalid input") // 400
return kori.Unauthorized("missing token") // 401
return kori.Forbidden("insufficient permissions") // 403
return kori.NotFound("user not found") // 404
return kori.Conflict("email already in use") // 409
return kori.UnprocessableEntity("invalid data") // 422
return kori.InternalServerError("unexpected err") // 500

Para status codes personalizados, use kori.NewError:

return kori.NewError(http.StatusTooManyRequests, "rate limit exceeded", map[string]int{
"retry_after": 60,
})

O segundo argumento é um detalhe estruturado opcional, incluído na resposta JSON em "details".

O Kori fornece helpers para escrever respostas. Cada um retorna o erro de escrita para que possa ser propagado:

kori.JSON(w, http.StatusOK, payload) // application/json
kori.RawJSON(w, http.StatusOK, rawBytes) // bytes JSON pré-codificados
kori.Text(w, http.StatusOK, "hello") // text/plain
kori.NoContent(w) // 204
kori.Redirect(w, r, http.StatusFound, "/new") // redirect
Helper Content-Type Escreve
JSON(w, status, v) application/json v codificado como JSON
RawJSON(w, status, data) application/json data como está, sem recodificar
Text(w, status, s) text/plain s como texto puro
NoContent(w) — 204 No Content, sem corpo
Redirect(w, r, status, url) — Um redirect para url com o status informado

RawJSON escreve bytes que já são JSON válido, evitando uma segunda codificação. Use para payloads em cache ou JSON produzido em outro lugar:

cached, err := cache.Get(ctx, key) // []byte, já é JSON
if err != nil {
return err
}
return kori.RawJSON(w, http.StatusOK, cached)

Redirect envolve http.Redirect e retorna nil, então compõe com a assinatura de handler que retorna erro. Informe o status explicitamente — http.StatusFound (302), http.StatusMovedPermanently (301) ou http.StatusSeeOther (303) após um POST bem-sucedido:

return kori.Redirect(w, r, http.StatusSeeOther, "/posts/"+post.ID)

Fluxo de erros explícito. Os erros sobem naturalmente. Não há como engolir um erro acidentalmente sem ignorar explicitamente o valor de retorno.

Tratamento centralizado. Uma única chamada a SetErrorHandler configura como todos os erros são renderizados. É possível trocar o formato inteiro — JSON, Problem Details, XML — em um único lugar:

kori.SetErrorHandler(func(w http.ResponseWriter, r *http.Request, err error) {
var he *kori.HTTPError
if !errors.As(err, &he) {
he = kori.InternalServerError("internal server error")
}
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(he.Status)
json.NewEncoder(w).Encode(he)
})

Menos boilerplate. A lógica da rota permanece focada no caminho feliz. Retornos antecipados propagam erros sem escrever respostas inline.

Compatível com net/http. Handlers Chi padrão e handlers Kori coexistem no mesmo router. A migração é incremental.