Pacote kori
Todas as funções, tipos e variáveis exportados de github.com/douglasmai4/kori.
import "github.com/douglasmai4/kori"Requer Go 1.26+ e github.com/go-chi/chi/v5.
Roteamento
Seção intitulada “Roteamento”Funções de método
Seção intitulada “Funções de método”func GET(r chi.Router, pattern string, h Handler, opts ...Option)func POST(r chi.Router, pattern string, h Handler, opts ...Option)func PUT(r chi.Router, pattern string, h Handler, opts ...Option)func PATCH(r chi.Router, pattern string, h Handler, opts ...Option)func DELETE(r chi.Router, pattern string, h Handler, opts ...Option)func HEAD(r chi.Router, pattern string, h Handler, opts ...Option)func OPTIONS(r chi.Router, pattern string, h Handler, opts ...Option)Registram h em r para o método HTTP correspondente. r pode ser qualquer chi.Router, inclusive um *kori.Router retornado por Group. Erros retornados por h vão para o ErrorHandler atual.
kori.GET(r, "/users", listUsers)kori.GET(r, "/users/{id}", getUser, kori.Use(adminOnly))func Group(r chi.Router, prefix string, middlewares ...Middleware) *RouterCria um sub-router montado em prefix com os middlewares informados. Grupos podem ser aninhados; o prefixo completo é rastreado para que options como o OpenAPI vejam o caminho inteiro.
users := kori.Group(r, "/users", authMiddleware)kori.GET(users, "/", listUsers)kori.GET(users, "/{id}", getUser)type Router struct { chi.Router // prefixo não exportado}Retornado por Group. Embute chi.Router, então todo método do Chi (Use, With, Get, Mount…) está disponível.
func Use(middlewares ...Middleware) OptionAnexa middlewares a uma única rota, em ordem, sem criar um sub-router.
kori.GET(r, "/admin", adminHandler, kori.Use(authMiddleware, auditMiddleware))Handlers e options
Seção intitulada “Handlers e options”Handler
Seção intitulada “Handler”type Handler func(w http.ResponseWriter, r *http.Request) errorA assinatura padrão de handler, retornando error. Retorne nil depois de escrever a resposta, ou retorne um erro e deixe o error handler escrevê-la.
Middleware
Seção intitulada “Middleware”type Middleware = func(http.Handler) http.HandlerAlias para o formato padrão de middleware. Qualquer middleware do Chi ou net/http funciona sem mudanças.
type Option func(*RouteInfo)Configura uma rota no momento do registro. Use e openapi.Spec.Route são options; você pode escrever as suas para criar loggers ou registros de rotas.
RouteInfo
Seção intitulada “RouteInfo”type RouteInfo struct { Method string Pattern string // campos não exportados}A rota sendo registrada, como vista por uma Option. Pattern inclui o prefixo do grupo.
Binding
Seção intitulada “Binding”Todos os binders decodificam em dst (ponteiro para struct) e depois validam com go-playground/validator usando tags validate. Erros de decodificação retornam 400; erros de validação retornam 422 com []ValidationDetail em details.
| Função | Origem | Tag da struct |
|---|---|---|
BindJSON(r, dst) |
Body da requisição (JSON) | json |
BindQuery(r, dst) |
Query string da URL | query |
BindPath(r, dst) |
Parâmetros de URL do Chi | path |
BindHeader(r, dst) |
Headers da requisição | header |
BindForm(r, dst) |
application/x-www-form-urlencoded |
form |
BindMultipart(r, dst) |
Valores e arquivos multipart/form-data |
form |
Bind(r, dst) |
Path, depois query, depois headers | path, query, header |
BindJSON
Seção intitulada “BindJSON”func BindJSON(r *http.Request, dst any) errorDecodifica o body como JSON. Body vazio pula a decodificação e só valida. Bodies acima do limite (4 MB por padrão) retornam 413 request body too large; JSON malformado retorna 400 invalid JSON body.
BindQuery
Seção intitulada “BindQuery”func BindQuery(r *http.Request, dst any) errorCampos slice coletam chaves repetidas: ?tag=a&tag=b preenche []string{"a", "b"}.
BindPath
Seção intitulada “BindPath”func BindPath(r *http.Request, dst any) errorLê valores com chi.URLParam. Exige que a requisição tenha sido roteada pelo Chi.
BindHeader
Seção intitulada “BindHeader”func BindHeader(r *http.Request, dst any) errorLê valores com r.Header.Get, então os nomes não diferenciam maiúsculas.
BindForm
Seção intitulada “BindForm”func BindForm(r *http.Request, dst any) errorFaz parse e decodifica r.PostForm. Retorna 400 cannot parse form body quando o parse falha.
BindMultipart
Seção intitulada “BindMultipart”func BindMultipart(r *http.Request, dst any) errorDecodifica valores e arquivos. Campos de arquivo devem ser *multipart.FileHeader ou []*multipart.FileHeader. Retorna 400 cannot parse multipart form quando o parse falha.
func Bind(r *http.Request, dst any) errorDecodifica path, query e headers na mesma struct e valida uma vez. Não lê o body.
Limites
Seção intitulada “Limites”func SetMaxBodyBytes(n int64) // limite do body no BindJSON, padrão 4 MBfunc SetMaxMultipartMemory(n int64) // limite multipart em memória, padrão 32 MBConfigurações globais. Chame na inicialização.
ValidationDetail
Seção intitulada “ValidationDetail”type ValidationDetail struct { Field string `json:"field"` Tag string `json:"tag"` Param string `json:"param,omitempty"` Message string `json:"message"`}Uma regra que falhou. Field usa o nome da tag (json, query, path, header ou form), não o nome do campo Go, então corresponde ao que o cliente enviou.
Respostas
Seção intitulada “Respostas”func JSON(w http.ResponseWriter, status int, v any) errorfunc RawJSON(w http.ResponseWriter, status int, data []byte) errorfunc Text(w http.ResponseWriter, status int, s string) errorfunc NoContent(w http.ResponseWriter) errorfunc Redirect(w http.ResponseWriter, r *http.Request, status int, url string) error| Função | Escreve |
|---|---|
JSON |
v codificado como JSON com Content-Type: application/json |
RawJSON |
Bytes JSON já codificados, sem alteração |
Text |
Um body text/plain |
NoContent |
204 No Content sem body |
Redirect |
Redirecionamento para url; status é 301, 302, 303, 307 ou 308 |
Cada uma retorna o erro de escrita, então return kori.JSON(...) é a última linha idiomática de um handler.
HTTPError
Seção intitulada “HTTPError”type HTTPError struct { Status int `json:"-"` Message string `json:"message"` Details any `json:"details,omitempty"`}
func (e *HTTPError) Error() stringUm erro estruturado com status. Retorne-o de um handler e o error handler escreve Status com {"message", "details"} no body.
Construtores
Seção intitulada “Construtores”func NewError(status int, message string, details ...any) *HTTPError
func BadRequest(msg string, details ...any) *HTTPError // 400func Unauthorized(msg string, details ...any) *HTTPError // 401func Forbidden(msg string, details ...any) *HTTPError // 403func NotFound(msg string, details ...any) *HTTPError // 404func Conflict(msg string, details ...any) *HTTPError // 409func UnprocessableEntity(msg string, details ...any) *HTTPError // 422func InternalServerError(msg string, details ...any) *HTTPError // 500Apenas o primeiro valor de details é usado.
return kori.Conflict("email already in use", map[string]string{"email": in.Email})ErrorHandler
Seção intitulada “ErrorHandler”type ErrorHandler func(w http.ResponseWriter, r *http.Request, err error)
func SetErrorHandler(h ErrorHandler)func GetErrorHandler() ErrorHandlerRecebe todo erro retornado por um handler. O padrão escreve *HTTPError como JSON e transforma qualquer outro erro em 500 {"message":"internal server error"}. SetErrorHandler é global e seguro para uso concorrente. Veja Respostas de erro customizadas.
Server-Sent Events
Seção intitulada “Server-Sent Events”NewSSEWriter
Seção intitulada “NewSSEWriter”func NewSSEWriter(w http.ResponseWriter) (*SSEWriter, error)Define os headers SSE, faz flush e retorna um writer. Retorna ErrStreamingNotSupported quando w não implementa http.Flusher.
Métodos do SSEWriter
Seção intitulada “Métodos do SSEWriter”func (s *SSEWriter) Send(event SSEEvent) errorfunc (s *SSEWriter) SendData(data string) errorfunc (s *SSEWriter) SendJSON(v any) errorfunc (s *SSEWriter) Ping() error| Método | Envia |
|---|---|
Send |
Um evento completo, com flush imediato |
SendData |
Um evento só com data, atalho para Send(SSEEvent{Data: data}) |
SendJSON |
v codificado como JSON em um evento só com data |
Ping |
Uma linha de comentário que mantém conexões ociosas vivas |
Um erro de escrita geralmente significa que o cliente desconectou; trate como fim do stream.
SSEEvent
Seção intitulada “SSEEvent”type SSEEvent struct { ID string Event string Data string Retry int}Campos vazios são omitidos. Data com várias linhas vira várias linhas data:.
ErrStreamingNotSupported
Seção intitulada “ErrStreamingNotSupported”var ErrStreamingNotSupported = errors.New("kori: response writer does not support streaming (does not implement http.Flusher)")