Install

Features

Examples

package mainimport ("net/http""github.com/go-chi/chi/v5""github.com/go-chi/chi/v5/middleware")funcmain() {r:=chi.NewRouter()r.Use(middleware.Logger)r.Get("/",func(w http.ResponseWriter,r*http.Request) {w.Write([]byte("welcome"))})http.ListenAndServe(":3000",r)}

import (//..."context""github.com/go-chi/chi/v5""github.com/go-chi/chi/v5/middleware")funcmain() {r:=chi.NewRouter()// A good base middleware stackr.Use(middleware.RequestID)r.Use(middleware.RealIP)r.Use(middleware.Logger)r.Use(middleware.Recoverer)// Set a timeout value on the request context (ctx), that will signal// through ctx.Done() that the request has timed out and further// processing should be stopped.r.Use(middleware.Timeout(60*time.Second))r.Get("/",func(w http.ResponseWriter,r*http.Request) {w.Write([]byte("hi"))  })// RESTy routes for "articles" resourcer.Route("/articles",func(r chi.Router) {r.With(paginate).Get("/",listArticles)// GET /articlesr.With(paginate).Get("/{month}-{day}-{year}",listArticlesByDate)// GET /articles/01-16-2017r.Post("/",createArticle)// POST /articlesr.Get("/search",searchArticles)// GET /articles/search// Regexp url parameters:r.Get("/{articleSlug:[a-z-]+}",getArticleBySlug)// GET /articles/home-is-toronto// Subrouters:r.Route("/{articleID}",func(r chi.Router) {r.Use(ArticleCtx)r.Get("/",getArticle)// GET /articles/123r.Put("/",updateArticle)// PUT /articles/123r.Delete("/",deleteArticle)// DELETE /articles/123    })  })// Mount the admin sub-routerr.Mount("/admin",adminRouter())http.ListenAndServe(":3333",r)}funcArticleCtx(next http.Handler) http.Handler {returnhttp.HandlerFunc(func(w http.ResponseWriter,r*http.Request) {articleID:=chi.URLParam(r,"articleID")article,err:=dbGetArticle(articleID)iferr!=nil {http.Error(w,http.StatusText(404),404)return    }ctx:=context.WithValue(r.Context(),"article",article)next.ServeHTTP(w,r.WithContext(ctx))  })}funcgetArticle(w http.ResponseWriter,r*http.Request) {ctx:=r.Context()article,ok:=ctx.Value("article").(*Article)if!ok {http.Error(w,http.StatusText(422),422)return  }w.Write([]byte(fmt.Sprintf("title:%s",article.Title)))}// A completely separate router for administrator routesfuncadminRouter() http.Handler {r:=chi.NewRouter()r.Use(AdminOnly)r.Get("/",adminIndex)r.Get("/accounts",adminListAccounts)returnr}funcAdminOnly(next http.Handler) http.Handler {returnhttp.HandlerFunc(func(w http.ResponseWriter,r*http.Request) {ctx:=r.Context()perm,ok:=ctx.Value("acl.permission").(YourPermissionType)if!ok||!perm.IsAdmin() {http.Error(w,http.StatusText(403),403)return    }next.ServeHTTP(w,r)  })}

Router interface

// Router consisting of the core routing methods used by chi's Mux,// using only the standard net/http.typeRouterinterface {http.HandlerRoutes// Use appends one or more middlewares onto the Router stack.Use(middlewares...func(http.Handler) http.Handler)// With adds inline middlewares for an endpoint handler.With(middlewares...func(http.Handler) http.Handler)Router// Group adds a new inline-Router along the current routing// path, with a fresh middleware stack for the inline-Router.Group(fnfunc(rRouter))Router// Route mounts a sub-Router along a `pattern` string.Route(patternstring,fnfunc(rRouter))Router// Mount attaches another http.Handler along ./pattern/*Mount(patternstring,h http.Handler)// Handle and HandleFunc adds routes for `pattern` that matches// all HTTP methods.Handle(patternstring,h http.Handler)HandleFunc(patternstring,h http.HandlerFunc)// Method and MethodFunc adds routes for `pattern` that matches// the `method` HTTP method.Method(method,patternstring,h http.Handler)MethodFunc(method,patternstring,h http.HandlerFunc)// HTTP-method routing along `pattern`Connect(patternstring,h http.HandlerFunc)Delete(patternstring,h http.HandlerFunc)Get(patternstring,h http.HandlerFunc)Head(patternstring,h http.HandlerFunc)Options(patternstring,h http.HandlerFunc)Patch(patternstring,h http.HandlerFunc)Post(patternstring,h http.HandlerFunc)Put(patternstring,h http.HandlerFunc)Trace(patternstring,h http.HandlerFunc)// NotFound defines a handler to respond whenever a route could// not be found.NotFound(h http.HandlerFunc)// MethodNotAllowed defines a handler to respond whenever a method is// not allowed.MethodNotAllowed(h http.HandlerFunc)}// Routes interface adds two methods for router traversal, which is also// used by the github.com/go-chi/docgen package to generate documentation for Routers.typeRoutesinterface {// Routes returns the routing tree in an easily traversable structure.Routes() []Route// Middlewares returns the list of middlewares in use by the router.Middlewares()Middlewares// Match searches the routing tree for a handler that matches// the method/path - similar to routing a http request, but without// executing the handler thereafter.Match(rctx*Context,method,pathstring)bool}

Middleware handlers

// HTTP middleware setting a value on the request contextfuncMyMiddleware(next http.Handler) http.Handler {returnhttp.HandlerFunc(func(w http.ResponseWriter,r*http.Request) {// create new context from `r` request context, and assign key `"user"`// to value of `"123"`ctx:=context.WithValue(r.Context(),"user","123")// call the next handler in the chain, passing the response writer and// the updated request object with the new context value.//// note: context.Context values are nested, so any previously set// values will be accessible as well, and the new `"user"` key// will be accessible from this point forward.next.ServeHTTP(w,r.WithContext(ctx))  })}

Request handlers

// HTTP handler accessing data from the request context.funcMyRequestHandler(w http.ResponseWriter,r*http.Request) {// here we read from the request context and fetch out `"user"` key set in// the MyMiddleware example above.user:=r.Context().Value("user").(string)// respond to the clientw.Write([]byte(fmt.Sprintf("hi %s",user)))}

URL parameters

// HTTP handler accessing the url routing parameters.funcMyRequestHandler(w http.ResponseWriter,r*http.Request) {// fetch the url parameter `"userID"` from the request of a matching// routing pattern. An example routing pattern could be: /users/{userID}userID:=chi.URLParam(r,"userID")// fetch `"key"` from the request contextctx:=r.Context()key:=ctx.Value("key").(string)// respond to the clientw.Write([]byte(fmt.Sprintf("hi %v, %v",userID,key)))}

Middlewares

Core middlewares

Extra middlewares & packages

context?

Benchmarks

BenchmarkChi_Param          3075895        384 ns/op      400 B/op      2 allocs/opBenchmarkChi_Param5         2116603        566 ns/op      400 B/op      2 allocs/opBenchmarkChi_Param20         964117       1227 ns/op      400 B/op      2 allocs/opBenchmarkChi_ParamWrite     2863413        420 ns/op      400 B/op      2 allocs/opBenchmarkChi_GithubStatic   3045488        395 ns/op      400 B/op      2 allocs/opBenchmarkChi_GithubParam    2204115        540 ns/op      400 B/op      2 allocs/opBenchmarkChi_GithubAll        10000     113811 ns/op    81203 B/op    406 allocs/opBenchmarkChi_GPlusStatic    3337485        359 ns/op      400 B/op      2 allocs/opBenchmarkChi_GPlusParam     2825853        423 ns/op      400 B/op      2 allocs/opBenchmarkChi_GPlus2Params   2471697        483 ns/op      400 B/op      2 allocs/opBenchmarkChi_GPlusAll        194220       5950 ns/op     5200 B/op     26 allocs/opBenchmarkChi_ParseStatic    3365324        356 ns/op      400 B/op      2 allocs/opBenchmarkChi_ParseParam     2976614        404 ns/op      400 B/op      2 allocs/opBenchmarkChi_Parse2Params   2638084        439 ns/op      400 B/op      2 allocs/opBenchmarkChi_ParseAll        109567      11295 ns/op    10400 B/op     52 allocs/opBenchmarkChi_StaticAll        16846      71308 ns/op    62802 B/op    314 allocs/op

Credits

Beyond REST

License