Core Concepts
To get up and running quickly,
macaron.Classic provides some reasonable defaults that work well for most of web applications:m := macaron.Classic()
// ... middleware and routing goes here
m.Run()
Any object with type
macaron.Macaron can be seen as an instance of Macaron, you can have as many instances as you'd like in a single piece of code.Handlers are the heart and soul of Macaron. A handler is basically any kind of callable function:
m.Get("/", func() string {
return "hello world"
})
Non-anonymous function is also allowed for the purpose of using it in multiple routes:
m.Get("/", myHandler)
m.Get("/hello", myHandler)
func myHandler() string {
return "hello world"
}
Besides, one route can have as many as handlers you want to register with:
m.Get("/", myHandler1, myHandler2)
func myHandler1() {
// ... do something
}
func myHandler2() string {
return "hello world"
}
If a handler returns something, Macaron will write the result to the current
http.ResponseWriter as a string:m.Get("/", func() string {
return "hello world" // HTTP 200 : "hello world"
})
m.Get("/", func() *string {
str := "hello world"
return &str // HTTP 200 : "hello world"
})
m.Get("/", func() []byte {
return []byte("hello world") // HTTP 200 : "hello world"
})
m.Get("/", func() error {
// Nothing happens if returns nil
return nil
}, func() error {
// ... get some error
return err // HTTP 500 : <error message>
})
You can also optionally return a status code (only applys for
string and []byte types):m.Get("/", func() (int, string) {
return 418, "i'm a teapot" // HTTP 418 : "i'm a teapot"
})
m.Get("/", func() (int, *string) {
str := "i'm a teapot"
return 418, &str // HTTP 418 : "i'm a teapot"
})
m.Get("/", func() (int, []byte) {
return 418, []byte("i'm a teapot") // HTTP 418 : "i'm a teapot"
})
Handlers are invoked via reflection. Macaron makes use of Dependency Injection to resolve dependencies in a Handlers argument list. This makes Macaron completely compatible with golang's
http.HandlerFunc interface.If you add an argument to your handler, Macaron will search its list of services and attempt to resolve the dependency via type assertion:
m.Get("/", func(resp http.ResponseWriter, req *http.Request) {
// resp and req are injected by Macaron
resp.WriteHeader(200) // HTTP 200
})
m.Get("/", func(ctx *macaron.Context) {
ctx.Resp.WriteHeader(200) // HTTP 200
})
Middleware Handlers sit between the incoming HTTP request and the router. In essence they are no different than any other Handler in Macaron. You can add a middleware handler to the stack like so:
m.Use(func() {
// do some middleware stuff
})
You can have full control over the middleware stack with the
Handlers function. This will replace any handlers that have been previously set:m.Handlers(
Middleware1,
Middleware2,
Middleware3,
)
Middleware Handlers work really well for things like logging, authorization, authentication, sessions, gzipping, error pages and any other operations that must happen before or after an HTTP request:
// validate an api key
m.Use(func(ctx *macaron.Context) {
if ctx.Req.Header.Get("X-API-KEY") != "secret123" {
ctx.Resp.WriteHeader(http.StatusUnauthorized)
}
})
Some Macaron handlers make use of the
macaron.Env global variable to provide special functionality for development environments vs production environments. It is recommended that the MACARON_ENV=production environment variable to be set when deploying a Macaron server into a production environment.
Handler Workflow
Last modified 3yr ago