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:
Getting Started
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
.
Need Help?
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.
Is Negroni a Framework?
Negroni is not a framework. It is a library that is designed to work directly with net/http.
Routing?
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()
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.
Handlers
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.Handler
s:
n := negroni.New()
mux := http.NewServeMux()
// map your routes
n.UseHandler(mux)
n.Run(":3000")
Run()
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))
Route Specific Middleware
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),
))
Third Party Middleware
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.) |
Examples
Alexander Rødseth created mooseware, a skeleton for writing a Negroni middleware handler.
Live code reload?
gin and fresh both live reload negroni apps.
Essential Reading for Beginners of Go & Negroni
About
Negroni is obsessively designed by none other than the Code Gangsta