Macaron Documentation
GitHub@unknwon
Search…
Welcome
Starter Guide
Core Concepts
Core Services
Custom Services
Middlewares
FAQs
简体中文
初学者指南
核心概念
核心服务
自定义服务
中间件和辅助模块
常见问题
Powered By GitBook
核心服务
Macaron 会注入一些默认服务来驱动您的应用，这些服务被称之为 核心服务。也就是说，您可以直接使用它们作为处理器参数而不需要任何附加工作。

请求上下文（Context）

该服务通过类型 *macaron.Context 来体现。这是 Macaron 最为核心的服务，您的任何操作都是基于它之上。该服务包含了您所需要的请求对象、响应流、模板引擎接口、数据存储和注入与获取其它服务。
使用方法：
1
package main
2
​
3
import "gopkg.in/macaron.v1"
4
​
5
func Home(ctx *macaron.Context) {
6
// ...
7
}
Copied!

Next()

方法 Context.Next 是一个可选的功能，它可以用于中间件处理器暂时放弃执行，等待其他的处理器都执行完毕后继续执行。这样就可以很好的处理在 HTTP 请求完成后需要做的操作：
1
// log before and after a request
2
m.Use(func(ctx *macaron.Context, log *log.Logger){
3
log.Println("before a request")
4
​
5
ctx.Next()
6
​
7
log.Println("after a request")
8
})
Copied!
最基本的 Cookie 用法：
使用方法：
1
// ...
2
m.Get("/set", func(ctx *macaron.Context) {
3
ctx.SetCookie("user", "Unknwon", 1)
4
})
5
​
6
m.Get("/get", func(ctx *macaron.Context) string {
7
return ctx.GetCookie("user")
8
})
9
// ...
Copied!
使用以下顺序的参数来设置更多的属性：SetCookie(<name>, <value>, <max age>, <path>, <domain>, <secure>, <http only>)。
因此，设置 Cookie 最完整的用法为：SetCookie("user", "unknwon", 999, "/", "localhost", true, true)。
需要注意的是，参数的顺序是固定的。
如果需要更加安全的 Cookie 机制，可以先使用 macaron.SetDefaultCookieSecret 设定密钥，然后使用：
这两个方法将会自动使用您设置的默认密钥进行加密/解密 Cookie 值。
使用方法：
1
// ...
2
m.SetDefaultCookieSecret("macaron")
3
m.Get("/set", func(ctx *macaron.Context) {
4
ctx.SetSecureCookie("user", "Unknwon", 1)
5
})
6
​
7
m.Get("/get", func(ctx *macaron.Context) string {
8
name, _ := ctx.GetSecureCookie("user")
9
return name
10
})
11
// ...
Copied!
对于那些对安全性要求特别高的应用，可以为每次设置 Cookie 使用不同的密钥加密/解密：
使用方法：
1
// ...
2
m.Get("/set", func(ctx *macaron.Context) {
3
ctx.SetSuperSecureCookie("macaron", "user", "Unknwon", 1)
4
})
5
​
6
m.Get("/get", func(ctx *macaron.Context) string {
7
name, _ := ctx.GetSuperSecureCookie("macaron", "user")
8
return name
9
})
10
// ...
Copied!

其它辅助方法

路由日志

该服务可以通过函数 macaron.Logger 来注入。该服务主要负责应用的路由日志。
使用方法：
1
package main
2
​
3
import "gopkg.in/macaron.v1"
4
​
5
func main() {
6
m := macaron.New()
7
m.Use(macaron.Logger())
8
// ...
9
}
Copied!
当您使用 macaron.Classic 时，该服务会被自动注入。
从 Peach Docs 项目中提取的样例输出：
1
[Macaron] Started GET /docs/middlewares/core.html for [::1]
2
[Macaron] Completed /docs/middlewares/core.html 200 OK in 2.114956ms
Copied!

容错恢复

该服务可以通过函数 macaron.Recovery 来注入。该服务主要负责在应用发生恐慌（panic）时进行恢复。
使用方法：
1
package main
2
​
3
import "gopkg.in/macaron.v1"
4
​
5
func main() {
6
m := macaron.New()
7
m.Use(macaron.Recovery())
8
// ...
9
}
Copied!
当您使用 macaron.Classic 时，该服务会被自动注入。

静态文件

该服务可以通过函数 macaron.Static 来注入。该服务主要负责应用静态资源的服务，当您的应用拥有多个静态目录时，可以对其进行多次注入。
使用方法：
1
package main
2
​
3
import "gopkg.in/macaron.v1"
4
​
5
func main() {
6
m := macaron.New()
7
m.Use(macaron.Static("public"))
8
m.Use(macaron.Static("assets"))
9
// ...
10
}
Copied!
当您使用 macaron.Classic 时，该服务会以 public 为静态目录被自动注入。
默认情况下，当您请求一个目录时，该服务不会列出目录下的文件，而是去寻找 index.html 文件。
从 Peach 项目中提取的样例输出：
1
[Macaron] Started GET /css/prettify.css for [::1]
2
[Macaron] [Static] Serving /css/prettify.css
3
[Macaron] Completed /css/prettify.css 304 Not Modified in 97.584us
4
[Macaron] Started GET /imgs/macaron.png for [::1]
5
[Macaron] [Static] Serving /imgs/macaron.png
6
[Macaron] Completed /imgs/macaron.png 304 Not Modified in 123.211us
7
[Macaron] Started GET /js/gogsweb.min.js for [::1]
8
[Macaron] [Static] Serving /js/gogsweb.min.js
9
[Macaron] Completed /js/gogsweb.min.js 304 Not Modified in 47.653us
10
[Macaron] Started GET /css/main.css for [::1]
11
[Macaron] [Static] Serving /css/main.css
12
[Macaron] Completed /css/main.css 304 Not Modified in 42.58us
Copied!

使用示例

假设您的应用拥有以下目录结构：
1
public/
2
|__ html
3
|__ index.html
4
|__ css/
5
|__ main.css
Copied!
响应结果：
请求 URL
匹配文件
/html/main.html
匹配失败
/html/
index.html
/css/main.css
main.css

自定义选项

该服务允许接受第二个参数来进行自定义选项操作（macaron.StaticOptions）：
1
package main
2
​
3
import "gopkg.in/macaron.v1"
4
​
5
func main() {
6
m := macaron.New()
7
m.Use(macaron.Static("public",
8
macaron.StaticOptions{
9
// 请求静态资源时的 URL 前缀，默认没有前缀
10
Prefix: "public",
11
// 禁止记录静态资源路由日志，默认为不禁止记录
12
SkipLogging: true,
13
// 当请求目录时的默认索引文件，默认为 "index.html"
14
IndexFile: "index.html",
15
// 用于返回自定义过期响应头，默认为不设置
16
// https://developers.google.com/speed/docs/insights/LeverageBrowserCaching
17
Expires: func() string {
18
return time.Now().Add(24 * 60 * time.Minute).UTC().Format("Mon, 02 Jan 2006 15:04:05 GMT")
19
},
20
}))
21
// ...
22
}
Copied!

注册多个静态处理器

如果您需要一次注册多个静态处理器，可以使用方法 macaron.Statics 来简化您的工作。
使用方法：
1
// ...
2
m.Use(macaron.Statics(macaron.StaticOptions{}, "public", "views"))
3
// ...
Copied!
这样，就可以同时注册 public 和 views 为静态目录了。

其它服务

全局日志

该服务通过类型 *log.Logger 来体现。该服务为可选，只是为没有日志器的应用提供一定的便利。
使用方法：
1
package main
2
​
3
import (
4
"log"
5
​
6
"gopkg.in/macaron.v1"
7
)
8
​
9
func main() {
10
m := macaron.Classic()
11
m.Get("/", myHandler)
12
m.Run()
13
}
14
​
15
func myHandler(ctx *macaron.Context, logger *log.Logger) string {
16
logger.Println("the request path is: " + ctx.Req.RequestURI)
17
return "the request path is: " + ctx.Req.RequestURI
18
}
Copied!
所有 Macaron 实例 都会自动注册该服务。

响应流

该服务通过类型 http.ResponseWriter 来体现。该服务为可选，一般情况下可直接使用 *macaron.Context.Resp。
使用方法：
1
package main
2
​
3
import (
4
"gopkg.in/macaron.v1"
5
)
6
​
7
func main() {
8
m := macaron.Classic()
9
m.Get("/", myHandler)
10
m.Run()
11
}
12
​
13
func myHandler(ctx *macaron.Context) {
14
ctx.Resp.Write([]byte("the request path is: " + ctx.Req.RequestURI))
15
}
Copied!
所有 Macaron 实例 都会自动注册该服务。

请求对象

该服务通过类型 *http.Request 来体现。该服务为可选，一般情况下可直接使用 *macaron.Context.Req。
除此之外，该服务还提供了 3 个便利的方法来获取请求体：
使用方法：
1
package main
2
​
3
import (
4
"gopkg.in/macaron.v1"
5
)
6
​
7
func main() {
8
m := macaron.Classic()
9
m.Get("/body1", func(ctx *macaron.Context) {
10
reader, err := ctx.Req.Body().ReadCloser()
11
// ...
12
})
13
m.Get("/body2", func(ctx *macaron.Context) {
14
data, err := ctx.Req.Body().Bytes()
15
// ...
16
})
17
m.Get("/body3", func(ctx *macaron.Context) {
18
data, err := ctx.Req.Body().String()
19
// ...
20
})
21
m.Run()
22
}
Copied!
需要注意的是，请求体在每个请求中只能被读取一次。
有时您需要传递类型为 *http.Request 的参数，则应该使用 *macaron.Context.Req.Request。
所有 Macaron 实例 都会自动注册该服务。
Previous
核心概念
Next
自定义服务
Last modified 1yr ago
Copy link
Contents
请求上下文（Context）
Next()
Cookie
其它辅助方法
路由日志
容错恢复
静态文件
使用示例
自定义选项
注册多个静态处理器
其它服务
全局日志
响应流
请求对象