chi/DOCS.md
Peter Kieltyka c416831d21 typo
2021-02-10 08:09:51 -05:00

150 lines
4.2 KiB
Markdown

chi, getting started
====================
Chi is a lightweight front-end to your HTTP server with it's sole job to help you handle HTTP requests.
With Chi, requests flow through a routing stack of (optional) middlewares and nested sub-routers,
all the way down to the final response handler. At any point down the chain of handlers, any of
the handlers may respond to the client and end the request flow.
Chi also comes with an expressive interface to allow you to specify different URL routing pattern
matchers, that as a request flows through, will mark the handler for processing of a request.
Chi is intentionally designed to not to try to do too much, and allow you to make your own opinions
on how you design your services. It's not a "web framework", but once you start putting together
all of its middlewares and your own patterns, it sure does feel as powerful as one. See the
[_examples]('./_examples) directory for some ideas on patterns you can compose with chi.
## Routing basics
**Routing an index page:**
```go
r := chi.NewRouter()
r.Get("/", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("index here"))
}
```
Note, in the above example we've inlined the http.HandlerFunc, however you can also define it
as a function and then reference it, like so:
```go
r := chi.NewRouter()
r.Get("/", indexHandler)
func indexHandler(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("index here"))
}
```
**Routing Page-Not-Found:**
```go
r := chi.NewRouter()
r.Get("/", indexHandler)
r.NotFound(func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(404)
w.Write([]byte("route does not exist"))
})
```
**Routing a POST request:**
```go
r := chi.NewRouter()
r.Post("/articles", createArticles)
func createArticles(w http.ResponseWriter, r *http.Request) {
// ..
w.WriteHeader(201)
})
```
**Routing other request methods:**
Chi allows you to route/handle any HTTP request method, such as all the usual suspects:
GET, POST, HEAD, PUT, PATCH, DELETE, OPTIONS, TRACE, CONNECT
These methods are defined on the `chi.Router` as:
```go
// HTTP-method routing along `pattern`
Connect(pattern string, h http.HandlerFunc)
Delete(pattern string, h http.HandlerFunc)
Get(pattern string, h http.HandlerFunc)
Head(pattern string, h http.HandlerFunc)
Options(pattern string, h http.HandlerFunc)
Patch(pattern string, h http.HandlerFunc)
Post(pattern string, h http.HandlerFunc)
Put(pattern string, h http.HandlerFunc)
Trace(pattern string, h http.HandlerFunc)
```
and may set a route by calling ie. `r.Put("/path", myHandler)`.
You may also register your own custom method names, by calling `chi.RegisterMethod("JELLO")`
and then setting the routing handler via `r.Method("JELLO", "/path", myJelloMethodHandler)`
## Routing patterns & url parameters
Each routing method accepts a URL `pattern` and chain of `handlers`. The URL pattern
supports named params (ie. `/users/{userID}`) and wildcards (ie. `/admin/*`). URL parameters
can be fetched at runtime by calling `chi.URLParam(r, "userID")` for named parameters
and `chi.URLParam(r, "*")` for a wildcard parameter.
**Routing a slug:**
```go
r := chi.NewRouter()
r.Get("/articles/{date}-{slug}", getArticle)
func getArticle(w http.ResponseWriter, r *http.Request) {
dateParam := chi.URLParam(r, "date")
slugParam := chi.URL(r, "slug")
article, err := database.GetArticle(date, slug)
if err != nil {
w.WriteHeader(422)
w.Write([]byte(fmt.Sprintf("error fetching article %s-%s: %v", dateParam, slugParam, err)))
return
}
if article == nil {
w.WriteHeader(404)
w.Write([]byte("article not found"))
return
}
w.Write([]byte(article.Text()))
})
```
as you can see above, the url parameters are defined using the curly brackets `{}` with the parameter
name in between, as `{date}` and `{slug}`. When a HTTP request is sent to the server and handled by
the chi router, if the URL path matches the format of "/articles/{date}-{slug}", then the `getArticle`
function will be called to send a response to the client.
For instance, URL paths like `/articles/20200109-this-is-so-cool` will match the route, however,
`/articles/1` will not.
## Middlewares
..
## Sub-routers
..
## What's next
auth, cors, etc..
..