Compare commits
2 commits
master
...
basic-docs
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
c416831d21 | ||
|
|
de5f84b91c |
2 changed files with 163 additions and 3 deletions
150
DOCS.md
Normal file
150
DOCS.md
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
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..
|
||||
|
||||
..
|
||||
16
README.md
16
README.md
|
|
@ -35,13 +35,23 @@ and [docgen](https://github.com/go-chi/docgen). We hope you enjoy it too!
|
|||
* **Go.mod support** - v1.x of chi (starting from v1.5.0), now has go.mod support (see [CHANGELOG](https://github.com/go-chi/chi/blob/master/CHANGELOG.md#v150-2020-11-12---now-with-gomod-support))
|
||||
* **No external dependencies** - plain ol' Go stdlib + net/http
|
||||
|
||||
## Getting started
|
||||
|
||||
Getting started with chi is as easy as...
|
||||
|
||||
1. Read the light [documentation](./DOCS.md)
|
||||
2. Check out the [_examples/](https://github.com/go-chi/chi/blob/master/_examples/)
|
||||
3. Finally, read the rest of this README for lots of little helpful tips.
|
||||
4. Read the source :)
|
||||
|
||||
glhf
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
See [_examples/](https://github.com/go-chi/chi/blob/master/_examples/) for a variety of examples.
|
||||
|
||||
|
||||
**As easy as:**
|
||||
**Hello world:**
|
||||
|
||||
```go
|
||||
package main
|
||||
|
|
@ -57,7 +67,7 @@ func main() {
|
|||
r := chi.NewRouter()
|
||||
r.Use(middleware.Logger)
|
||||
r.Get("/", func(w http.ResponseWriter, r *http.Request) {
|
||||
w.Write([]byte("welcome"))
|
||||
w.Write([]byte("hello world"))
|
||||
})
|
||||
http.ListenAndServe(":3000", r)
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue