Macaron Documentation
  • Welcome
  • Starter Guide
  • Core Concepts
  • Core Services
  • Custom Services
  • Middlewares
    • Routing
    • Templating
    • Gzip
    • Localization
    • Data Binding and Validation
    • Cache
    • Captcha
    • Session
    • Cross-Site Request Forgery
    • Embed Binary Data
    • Serving Multiple Sites
  • FAQs
  • 简体中文
    • 初学者指南
    • 核心概念
    • 核心服务
    • 自定义服务
    • 中间件和辅助模块
      • 路由模块
      • 模板引擎
      • Gzip 压缩
      • 应用本地化
      • 数据绑定与验证
      • 缓存管理(Cache)
      • 验证码服务
      • 会话管理(Session)
      • 跨域请求攻击(CSRF)
      • 嵌入二进制数据
      • 服务多个站点
    • 常见问题
Powered by GitBook
On this page
  • Classic Macaron
  • Instances
  • Handlers
  • Return Values
  • Service Injection
  • Middleware Handlers
  • Macaron Env
  • Handler Workflow

Was this helpful?

Core Concepts

PreviousStarter GuideNextCore Services

Last updated 5 years ago

Was this helpful?

Classic Macaron

To get up and running quickly, provides some reasonable defaults that work well for most of web applications:

m := macaron.Classic()
// ... middleware and routing goes here
m.Run()

Below is some of the functionality pulls in automatically:

  • Request/response logging -

  • Panic recovery -

  • Static file serving -

Instances

Any object with type 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

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"
}

Return Values

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"
})

Service Injection

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

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)
    }
})

Macaron Env

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

If a handler returns something, Macaron will write the result to the current as a string:

Handlers are invoked via reflection. Macaron makes use of to resolve dependencies in a Handlers argument list. This makes Macaron completely compatible with golang's interface.

The most commonly used service in your code should be :

The following services are included with :

- HTTP request context

- Global logger for Macaron instances

- HTTP Response writer interface

- HTTP Request

http.ResponseWriter
Dependency Injection
http.HandlerFunc
macaron.Classic
macaron.Classic
macaron.Classic
macaron.Macaron
Handler Workflow
macaron.Logger
macaron.Recovery
macaron.Static
*macaron.Context
*macaron.Context
*log.Logger
http.ResponseWriter
*http.Request