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.
Language Translations:
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 middleware 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.Handlers:
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))If you have a route group of routes that need specific middleware to be executed, you can simply create a new Negroni instance and use it as your route handler.
router := mux.NewRouter()
adminRoutes := mux.NewRouter()
// add admin routes here
// Create a new negroni for the admin middleware
router.Handle("/admin", negroni.New(
Middleware1,
Middleware2,
negroni.Wrap(adminRoutes),
))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 |
|---|---|---|
| RestGate | Prasanga Siripala | Secure authentication for REST API endpoints |
| Graceful | Tyler Bunnell | Graceful HTTP Shutdown |
| secure | Cory Jacobsen | Middleware that implements a few quick security wins |
| JWT Middleware | Auth0 | Middleware checks for a JWT on the Authorization header on incoming requests and decodes it |
| binding | Matt Holt | Data binding from HTTP requests into structs |
| logrus | Dan Buch | Logrus-based logger |
| render | Cory Jacobsen | Render JSON, XML and HTML templates |
| gorelic | Jingwen Owen Ou | New Relic agent for Go runtime |
| gzip | phyber | GZIP response compression |
| oauth2 | David Bochenski | oAuth2 middleware |
| sessions | David Bochenski | Session Management |
| permissions2 | Alexander Rødseth | Cookies, users and permissions |
| onthefly | Alexander Rødseth | Generate TinySVG, HTML and CSS on the fly |
| cors | Olivier Poitrey | Cross Origin Resource Sharing (CORS) support |
| xrequestid | Andrea Franz | Middleware that assigns a random X-Request-Id header to each request |
| VanGoH | Taylor Wrobel | Configurable AWS-Style HMAC authentication middleware |
| stats | Florent Messa | Store information about your web application (response time, etc.) |
Alexander Rødseth created mooseware, a skeleton for writing a Negroni middleware handler.
gin and fresh both live reload negroni apps.
Negroni is obsessively designed by none other than the Code Gangsta