Pular para o conteúdo

Tratamento de Erros

A diferença mais visível entre um handler Kori e um handler Chi puro é o tipo de retorno.

// Chi puro
func handler(w http.ResponseWriter, r *http.Request) { ... }
// Kori
func handler(w http.ResponseWriter, r *http.Request) error { ... }

Retorne qualquer error de um handler. O Kori o intercepta e escreve a resposta.

func getUser(w http.ResponseWriter, r *http.Request) error {
user, err := db.Find(chi.URLParam(r, "id"))
if err != nil {
return kori.NotFound("user not found")
}
return kori.JSON(w, http.StatusOK, user)
}

As regras são:

Valor retornado Comportamento
nil Nada — você já escreveu a resposta
*kori.HTTPError Resposta 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

Todos aceitam um segundo argumento opcional para detalhes estruturados:

return kori.NotFound("user not found", map[string]string{
"id": chi.URLParam(r, "id"),
})
return kori.NewError(http.StatusTooManyRequests, "rate limit exceeded", map[string]int{
"retry_after": 60,
})

Quando um handler retorna um *kori.HTTPError, o handler de erro padrão escreve:

{
"message": "user not found"
}

Com detalhes:

{
"message": "rate limit exceeded",
"details": { "retry_after": 60 }
}

Erros desconhecidos (qualquer coisa que não seja *kori.HTTPError) produzem:

{
"message": "internal server error"
}

Substitua o handler padrão com kori.SetErrorHandler. Chame uma vez na inicialização, antes de qualquer requisição ser tratada.

kori.SetErrorHandler(func(w http.ResponseWriter, r *http.Request, err error) {
var he *kori.HTTPError
if !errors.As(err, &he) {
slog.Error("unhandled error", "err", err, "path", r.URL.Path)
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)
})

Um caso de uso comum é o RFC 7807 Problem Details:

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/problem+json")
w.WriteHeader(he.Status)
json.NewEncoder(w).Encode(map[string]any{
"type": "https://api.example.com/errors",
"status": he.Status,
"detail": he.Message,
})
})

kori.GetErrorHandler retorna o handler em uso no momento. Use-o para adicionar comportamento ao redor do existente — logging, métricas, tracing — em vez de reimplementar o formato da resposta:

base := kori.GetErrorHandler()
kori.SetErrorHandler(func(w http.ResponseWriter, r *http.Request, err error) {
slog.Error("request failed", "err", err, "path", r.URL.Path)
base(w, r, err)
})

Capture base antes de chamar SetErrorHandler, não dentro do novo handler — caso contrário ele chamaria a si mesmo.

type HTTPError struct {
Status int `json:"-"`
Message string `json:"message"`
Details any `json:"details,omitempty"`
}

Você pode construir um diretamente para status codes customizados:

return kori.NewError(http.StatusPaymentRequired, "payment required")
return kori.NewError(http.StatusServiceUnavailable, "service unavailable", map[string]string{
"reason": "database unreachable",
})