Negroni is an idiomatic approach to web middleware in Go. It is tiny, non-intrusive, and encourages use of net/http
Handlers.
If you like the idea of Martini, but you think it contains too much magic, then Negroni is a great fit.
After installing Go and setting up your GOPATH, create your first .go
file. We'll call it server.go
.
package main
import (
"github.com/codegangsta/negroni"
"net/http"
"fmt"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
fmt.Fprintf(w, "Welcome to the home page!")
})
n := negroni.Classic()
n.UseHandler(mux)
n.Run(":3000")
}
Then install the Negroni package (go 1.1 and greater is required):
go get github.com/codegangsta/negroni
Then run your server:
go run server.go
You will now have a Go net/http webserver running on localhost:3000
.
If you have a question or feature request, go ask the mailing list. The GitHub issues for Negroni will be used exclusively for bug reports and pull requests.
Negroni is not a framework. It is a library that is designed to work directly with net/http.
Negroni is BYOR (Bring your own Router). The Go community already has a number of great http routers available, Negroni tries to play well with all of them by fully supporting net/http
. For instance, integrating with Gorilla Mux looks like so:
router := mux.NewRouter()
router.HandleFunc("/", HomeHandler)
n := negroni.New(Middleware1, Middleware2)
// Or use a middleware with the Use() function
n.Use(Middleware3)
// router goes last
n.UseHandler(router)
n.Run(":3000")
negroni.Classic()
provides some default middleware that is useful for most applications:
negroni.Recovery
- Panic Recovery Middleware.negroni.Logging
- Request/Response Logging Middleware.negroni.Static
- Static File serving under the "public" directory.
This makes it really easy to get started with some useful features from Negroni.
Negroni provides a bidirectional middleware flow. This is done through the negroni.Handler
interface:
type Handler interface {
ServeHTTP(rw http.ResponseWriter, r *http.Request, next http.HandlerFunc)
}
If a middlware hasn't already written to the ResponseWriter, it should call the next http.HandlerFunc
in the chain to yield to the next middleware handler. This can be used for great good:
func MyMiddleware(rw http.ResponseWriter, r *http.Request, next http.HandlerFunc) {
// do some stuff before
next(rw, r)
// do some stuff after
}
And you can map it to the handler chain with the Use
function:
n := negroni.New()
n.Use(negroni.HandlerFunc(MyMiddleware))
You can also map plain old http.Handler
's:
n := negroni.New()
mux := http.NewServeMux()
// map your routes
n.UseHandler(mux)
n.Run(":3000")
Negroni has a convenience function called Run
. Run
takes an addr string identical to http.ListenAndServe.
n := negroni.Classic()
// ...
log.Fatal(http.ListenAndServe(":8080", n))
Here is a current list of Negroni compatible middlware. Feel free to put up a PR linking your middleware if you have built one:
Middleware | Author | Description |
---|---|---|
Graceful | Tyler Bunnell | Graceful HTTP Shutdown |
secure | Cory Jacobsen | Middleware that implements a few quick security wins |
binding | Matt Holt | Data binding from HTTP requests into structs |
logrus | Dan Buch | Logrus-based logger |
render | Cory Jacobsen | Package for rendering JSON, XML, and HTML templates |
gorelic | Jingwen Owen Ou | New Relic agent for Go runtime |
gzip | phyber | GZIP response compression |
gin and fresh both live reload negroni apps.
Negroni is obsessively designed by none other than the Code Gangsta