Pular para o conteúdo

O que é o Kori?

O Kori é um toolkit para o Chi que reduz o boilerplate comum em serviços HTTP em Go — sem substituir nada em que você já depende.

net/http, Chi e middlewares padrão continuam funcionando exatamente como antes. O Kori constrói sobre eles.

Escrever handlers HTTP em Go com Chi é direto, mas os mesmos padrões se repetem em todo projeto:

  • Decodificar o corpo da requisição e tratar o erro de decodificação
  • Validar a struct, formatar e retornar os erros de validação
  • Escrever a resposta com o Content-Type e o status code corretos
  • Retornar o erro HTTP adequado em cada caso de borda

Nada disso é difícil, mas adiciona ruído a cada handler. O Kori remove esse ruído mantendo a estrutura familiar.

Feature Descrição
Handlers com retorno de erro Handler é func(w, r) error. Retorne um erro; o Kori cuida da resposta.
Helpers de binding BindJSON, BindQuery, BindPath, BindHeader, BindForm, BindMultipart
Validação automática Powered by go-playground/validator. Entradas inválidas retornam respostas 422 estruturadas.
Helpers de resposta JSON, Text, NoContent, Redirect, RawJSON
Erros HTTP tipados NotFound, BadRequest, Conflict, Unauthorized, e mais
Groups kori.Group para sub-routers com prefixo e middleware de grupo
Middleware por rota kori.Use(...) anexa middleware a uma única rota sem sub-router
SSE SSEWriter para Server-Sent Events
OpenAPI Módulo opcional kori/openapi gera specs OpenAPI 3.1 a partir das suas rotas

O Kori não é um framework. Ele não substitui:

  • net/http — http.ResponseWriter e *http.Request permanecem a assinatura da função
  • Chi — roteamento, middleware, URL params e sub-routers continuam sendo Chi
  • Middlewares padrão — qualquer func(http.Handler) http.Handler funciona sem alterações

O mesmo router pode servir handlers Chi padrão e handlers Kori lado a lado:

r := chi.NewRouter()
r.Use(chimiddleware.Logger) // middleware Chi padrão
// handler Chi padrão — sem alterações
r.Get("/health", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("ok"))
})
// handler Kori no mesmo router
kori.GET(r, "/users", listUsers)
kori.POST(r, "/users", createUser)

Uma API pequena mas completa usando os recursos principais do Kori:

package main
import (
"net/http"
"github.com/go-chi/chi/v5"
"github.com/douglasmai4/kori"
)
type CreateUserBody struct {
Name string `json:"name" validate:"required,min=2"`
Email string `json:"email" validate:"required,email"`
}
type UserParams struct {
ID string `path:"id" validate:"required,uuid4"`
}
func main() {
r := chi.NewRouter()
kori.GET(r, "/users/{id}", getUser)
kori.POST(r, "/users", createUser)
http.ListenAndServe(":8080", r)
}
func getUser(w http.ResponseWriter, r *http.Request) error {
var p UserParams
if err := kori.BindPath(r, &p); err != nil {
return err // 422 com detalhes por campo
}
user, err := db.Find(p.ID)
if err != nil {
return kori.NotFound("user not found")
}
return kori.JSON(w, http.StatusOK, user)
}
func createUser(w http.ResponseWriter, r *http.Request) error {
var body CreateUserBody
if err := kori.BindJSON(r, &body); err != nil {
return err // 400 para JSON inválido, 422 para erros de validação
}
user, err := db.Create(body.Name, body.Email)
if err != nil {
return kori.Conflict("email already in use")
}
return kori.JSON(w, http.StatusCreated, user)
}

A assinatura do handler é func(w http.ResponseWriter, r *http.Request) error — um valor de retorno a mais, nada mais mudou.