• 后端

本文以当前仓库 README.md 为主线，结合仓库内 martini.go、router.go、static.go 等核心源码与对应测试，系统讲解 Martini 框架的启动方式、处理器（Handler）与依赖注入、路由匹配、服务映射、静态文件、中间件与Next()等核心机制，并给出与既有 Go 服务器集成、端口配置、环境区分等实战方案。读完本文，你将能够独立搭建一个基于 Martini 的模块化 Web 应用，并理解其"一切皆可注入、一切皆中间件"的设计原理。

维护状态说明：README 顶部明确注明 "The martini framework is no longer maintained"，即该项目已停止维护。本文所讲内容基于当前仓库的实际代码与文档，适合作为学习经典 Go Web 框架设计、阅读源码或维护存量项目的参考，不推荐用于全新生产项目选型。

快速开始：第一个 Martini 应用

Martini 是一个用于在 Golang 中快速编写模块化 Web 应用/服务的包。启动一个应用只需要三步：创建入口文件、安装依赖、运行。

在安装 Go 并设置好GOPATH后，创建你的第一个.go文件（这里命名为server.go）：

package main import "github.com/go-martini/martini" func main() { m := martini.Classic() m.Get("/", func() string { return "Hello world!" }) m.Run() }

然后安装 Martini 包（要求 Go 1.1 或更高版本）：

go get github.com/go-martini/martini

接着运行你的服务：

go run server.go

此时一个 Martini Web 服务已经监听在localhost:3000，访问根路径即可看到Hello world!。

关于 Go 版本要求，仓库用了一个巧妙的手段来保证：在 go_version.go 中通过构建标签// +build !go1.1声明"非 Go 1.1"环境才编译该文件，文件内的MartiniDoesNotSupportGo1Point0()函数会触发编译错误，从而在编译期阻止 Go 1.0 及以下版本使用本框架。从 Godeps/Godeps.json 可以看到，本项目当时基于 Go 1.4.2，唯一的第三方依赖是github.com/codegangsta/inject（v1.0-rc1 附近的修订版本），这正是实现依赖注入的基础库。

特性总览

README 中列出了 Martini 的核心特性，结合源码可以逐条印证：

• 使用极其简单：三条语句即可启动一个服务（见上文server.go）。
• 无侵入式设计：Martini 实例实现了标准库http.Handler接口，可无缝嵌入既有 Go 服务。
• 与其它 Go 包协同良好：路由匹配基于标准库regexp，响应基于net/http，不引入自有类型绑架。
• 出色的路径匹配与路由：支持命名参数、glob、正则表达式三种模式（详见下文"路由"章节）。
• 模块化设计：中间件通过Use/Handlers按需增减，内置组件各自独立成文件。
• 大量可直接使用的处理器/中间件：仓库内自带 Logger、Recovery、Static，社区侧有 martini-contrib 生态。
• 开箱即用的功能集：Classic()一次性装配好日志、panic 恢复、静态文件与路由。
• 完全兼容http.HandlerFunc接口：这是 Martini 设计的基石，详情见下文"依赖注入"。
• 默认文档服务：Static 中间件支持 Fallback 回退，可直接支撑 AngularJS 等 SPA 在 HTML5 history 模式下的部署。

Classic Martini：开箱即用的默认装配

要快速启动，martini.Classic()提供了对大多数 Web 应用都适用的合理默认值：

m := martini.Classic() // ... 中间件与路由在这里编写 m.Run()

从源码看，Classic()的实现在 martini.go：

func Classic() *ClassicMartini { r := NewRouter() m := New() m.Use(Logger()) m.Use(Recovery()) m.Use(Static("public")) m.MapTo(r, (*Routes)(nil)) m.Action(r.Handle) return &ClassicMartini{m, r} }

它自动拉入以下四类功能：

与Classic()相对的是New()，后者创建一个"裸"的 Martini 实例，不装配任何中间件与路由，适合希望对中间件栈有完全控制的场景。New()内部（martini.go）只做两件事：创建一个基于inject.New()的依赖注入容器，并把默认的ReturnHandler（返回值处理器）映射为服务。此外它还会创建一个前缀为[martini]的输出到os.Stdout的*log.Logger，并默认注入。你可以用m.Logger(logger)随时替换全局日志器。

Handlers：处理器的灵魂

处理器（Handler）是 Martini 的心脏与灵魂。一个处理器"基本上可以是任何可调用函数"——在 martini.go 中，Handler被定义为interface{}，注册时通过反射校验其类型必须为函数：

func validateHandler(handler Handler) { if reflect.TypeOf(handler).Kind() != reflect.Func { panic("martini handler must be a callable func") } }

最简单的处理器不返回任何值：

m.Get("/", func() { println("hello world") })

返回值：自动写入响应

如果一个处理器返回了值，Martini 会把它作为字符串写入当前的http.ResponseWriter：

m.Get("/", func() string { return "hello world" // HTTP 200 : "hello world" })

你还可以选择性地返回一个状态码：

m.Get("/", func() (int, string) { return 418, "i'm a teapot" // HTTP 418 : "i'm a teapot" })

这一机制的实际执行者是默认的ReturnHandler，实现位于 return_handler.go。其判定逻辑值得细看：

• 当返回值多于一个且第一个值的类型是int时，把第一个值作为状态码写入WriteHeader，第二个值作为响应体；
• 否则取第一个返回值作为响应体；
• 响应体支持[]byte（字节切片直接Write），也支持任意可String()化的值；
• 如果返回值是指针或接口类型，会自动解引用后再处理。

router_test.go 中的Test_RouterHandlerStatusCode完整验证了这些行为：返回string得到 200；返回(int, string)会采用该状态码（如 403）；返回两个字符串时，因为第一个不是整数，不会被误当作状态码；返回[]byte与interface{}也能正确渲染。

服务注入：反射调用 + 依赖注入

处理器是通过反射调用的。Martini 使用**依赖注入（Dependency Injection）**来解析处理器参数列表中的依赖——你往处理器里加什么参数，Martini 就去服务容器里按类型查找并注入。这正是 Martini 与 Go 标准库http.HandlerFunc接口完全兼容的根本原因。

m.Get("/", func(res http.ResponseWriter, req *http.Request) { // res 和 req 由 Martini 注入 res.WriteHeader(200) // HTTP 200 })

在Classic()模式下，以下服务已经内置在容器中，可在任意处理器参数中直接声明使用：

若某个参数类型在容器中无法被满足，Martini 会直接panic（参见 context.run() 中对Invoke错误的处理）。

Routing：路由与匹配模式

在 Martini 中，一条路由 = 一个 HTTP 方法 + 一个 URL 匹配模式。每条路由可以挂载一个或多个处理器：

m.Get("/", func() { // 显示 }) m.Patch("/", func() { // 更新 }) m.Post("/", func() { // 创建 }) m.Put("/", func() { // 替换 }) m.Delete("/", func() { // 销毁 }) m.Options("/", func() { // http options }) m.NotFound(func() { // 处理 404 })

除了上述方法，Router 接口 还提供了Head、Any（匹配任意方法）以及可自定义方法名的AddRoute(method, pattern, ...)。

路由按定义顺序匹配，最先匹配成功的路由被调用。从 router.Handle() 的源码可以看到，匹配时按路由注册顺序遍历，每轮比较RouteMatch优先级，只有出现ExactMatch（完全精确匹配）才会提前终止循环。

命名参数

路由模式可以包含命名参数，通过martini.Params服务访问：

m.Get("/hello/:name", func(params martini.Params) string { return "Hello " + params["name"] })

Glob 匹配

路由支持 glob 通配，捕获的参数依次命名为_1、_2……：

m.Get("/hello/**", func(params martini.Params) string { return "Hello " + params["_1"] })

正则表达式

路由也可以直接使用正则表达式（语法遵循 Go 官方 regexp 文档）：

m.Get("/hello/(?P<name>[a-zA-Z]+)", func(params martini.Params) string { return fmt.Sprintf ("Hello %s", params["name"]) })

路由模式的编译原理

三种模式其实都统一编译为regexp.Regexp，见 newRoute()：

• 命名参数通过正则:[^/#?()\.\\]+被替换为命名捕获组(?P<name>[^/#?]+)；
• glob**通过正则\*\*被替换为(?P<_n>[^#?]*)（下标从 1 递增）；
• 用户直接书写的(?P<name>...)保持原样，最终整体追加一个可选的尾斜杠\/?后编译。

匹配优先级用RouteMatch枚举表示（router.go）：NoMatch < StarMatch（Any 通配方法）< OverloadMatch（HEAD 命中 GET）< ExactMatch，数值越大越优。其中OverloadMatch意味着：HEAD 请求会自动降级匹配到同路径的 GET 路由，这在 router_test.go 的Test_RouteMatching表驱动用例中有直接验证。

处理器叠加

路由处理器可以层层叠加，非常适合鉴权、授权等场景：

m.Get("/secret", authorize, func() { // 只要 authorize 没有写入响应，这里的代码就会执行 })

路由分组 Group

使用Group方法可以把相关路由编为一组：

m.Group("/books", func(r martini.Router) { r.Get("/:id", GetBooks) r.Post("/new", NewBook) r.Put("/update/:id", UpdateBook) r.Delete("/delete/:id", DeleteBook) })

和给处理器传中间件一样，也可以给整个组传中间件：

m.Group("/books", func(r martini.Router) { r.Get("/:id", GetBooks) r.Post("/new", NewBook) r.Put("/update/:id", UpdateBook) r.Delete("/delete/:id", DeleteBook) }, MyMiddleware1, MyMiddleware2)

从源码看，Group() 的实现是把组前缀和组中间件压入一个栈，组内addRoute时再把栈内所有前缀拼接、中间件前置合并（router.go）。这也意味着分组可以嵌套，router_test.go的Test_Routing中用三层嵌套分组验证了 "group + ception" 的执行顺序。

路由辅助服务 Routes

Classic()会把路由表以Routes服务的形式注入容器，处理器内可直接使用：

• URLFor(name, params...)：按路由名反向生成 URL，参数可以是整数或字符串（router.go），用于在模板或链接中动态生成地址；
• MethodsFor(path)：返回某路径下已注册的全部 HTTP 方法，可用于生成 405 响应的Allow头（见Test_MethodsFor，返回GET,PUT之类的值）；
• All()：返回全部路由，便于调试与文档生成。

路由对象本身也支持Name(...)命名，配合URLFor使用。

Services：服务与依赖注入

服务是可供处理器参数注入的对象。你可以把服务映射到全局或请求两个级别。

全局映射（Global Mapping）

Martini 实例实现了inject.Injector接口，因此全局映射一行即可：

db := &MyDatabase{} m := martini.Classic() m.Map(db) // 该服务对所有处理器以 *MyDatabase 类型可用 // ... m.Run()

请求级映射（Request-Level Mapping）

请求级映射在处理器内通过martini.Context完成：

func MyCustomLoggerHandler(c martini.Context, req *http.Request) { logger := &MyCustomLogger{req} c.Map(logger) // 以 *MyCustomLogger 映射 }

从 createContext() 可以看到，每个请求都会基于inject.New()新建一个上下文注入器，并以当前 Martini 实例为父级（SetParent(m)），同时把Context、包装后的ResponseWriter和*http.Request注入进去——这正是请求级服务与全局服务能共存的容器结构。

映射值到接口

服务机制最强大的一点是可以把具体对象映射到接口类型。例如要覆盖http.ResponseWriter，用一个包装对象执行额外操作：

func WrapResponseWriter(res http.ResponseWriter, c martini.Context) { rw := NewSpecialResponseWriter(res) c.MapTo(rw, (*http.ResponseWriter)(nil)) // 用包装后的 ResponseWriter 覆盖原接口 }

配合仓库自带的 ResponseWriter，中间件可以精确控制响应生命周期：它实现了标准接口外加Status()（状态码，未写入时为 0）、Written()（是否已写响应）、Size()（已写入字节数）、Before(BeforeFunc)（在写入响应前回调，callBefore按逆序执行，见 response_writer.go），并透传Flusher、Hijacker、CloseNotifier能力——response_writer_test.go中的Test_ResponseWriter_FlusherHandler就是用它实现的 SSE（Server-Sent Events）流式输出示例。

Serving Static Files：静态文件服务

Classic()实例默认从应用根目录下的public目录提供静态文件。想增加更多目录，添加martini.Static处理器即可：

m.Use(martini.Static("assets")) // 同时从 "assets" 目录提供静态文件

StaticOptions 配置项

Static接受可选的StaticOptions（定义见 static.go），完整参数如下：

Static中间件只处理GET与HEAD请求，其它方法直接放行（static.go）；访问目录但缺少尾斜杠时会 302 重定向补全斜杠；最终通过http.ServeContent输出文件并附带Last-Modified等标准头。以上行为在 static_test.go 中均有对应测试，包括Prefix挂载、Expires头注入、IndexFile索引、Fallback回退与目录重定向。

服务默认文档（SPA 场景）

你可以指定一个本地文件，在请求的 URL 找不到对应资源时兜底返回；同时指定一个排除前缀，让某些 URL 不被静态处理。这种组合非常适合"既提供静态文件、又暴露 REST API"的服务——把静态处理器挂到 NotFound 链上即可：

static := martini.Static("assets", martini.StaticOptions{Fallback: "/index.html", Exclude: "/api/v"}) m.NotFound(static, http.NotFound)

上述配置的效果是：任何既未命中本地文件、又以/api/v开头的 URL（如/api/v1/users），都交给后续的http.NotFound；其余未命中静态资源的 URL 则统一返回/index.html，从而让 AngularJS 等前端框架的 history 路由刷新后不至于 404。

Middleware Handlers：中间件

中间件处理器位于入站 HTTP 请求与路由之间，本质上与 Martini 的任何其它处理器没有区别。通过Use把它加入处理链：

m.Use(func() { // 做一些中间件该做的事 })

Handlers函数可以整体接管中间件栈——它会清空并替换此前设置的所有处理器：

m.Handlers( Middleware1, Middleware2, Middleware3, )

从 Handlers() 实现 看，它只是重置handlers切片后逐个Use。Test_Martini_Handlers（martini_test.go）验证了替换后的执行顺序。

中间件非常适合日志、授权、认证、会话、gzip、错误页等一切必须在请求前或请求后执行的操作：

// 校验 API 密钥 m.Use(func(res http.ResponseWriter, req *http.Request) { if req.Header.Get("X-API-KEY") != "secret123" { res.WriteHeader(http.StatusUnauthorized) } })

Next()：在其它处理器之后继续

Context.Next()是一个可选函数，中间件处理器调用它后会让出执行权，直到后续处理器执行完毕再回来——这对"请求之后"的操作非常有用：

// 在请求前后分别记录日志 m.Use(func(c martini.Context, log *log.Logger){ log.Println("before a request") c.Next() log.Println("after a request") })

其实现原理见 context.Next() / context.run()：Next()只是把index前移并再次进入run()循环；run()逐个Invoke处理器，一旦发现响应已被写入（Written()为 true）就立即短路返回，后续处理器不再执行。这个"写入即短路"语义正是叠加处理器与鉴权中间件能正确工作的关键，Test_Martini_ServeHTTP与Test_Martini_EarlyWrite（martini_test.go）用字符串拼接的方式精确验证了洋葱模型式的执行轨迹。

内置中间件源码解析

Logger（logger.go）：请求进入时打印Started {method} {path} for {addr}（IP 优先取X-Real-IP，其次X-Forwarded-For，最后RemoteAddr），调用c.Next()后打印Completed {status} {text} in {duration}，方便排查线上问题。

Recovery（recovery.go）：用defer/recover捕获处理器 panic，记录完整调用栈（stack()会读取源文件还原出错行）。它读取当前注入的ResponseWriter写出 500 响应——在开发环境（Env == Dev）返回渲染好的 HTML 错误页（红色PANIC页面，含错误信息与栈），生产环境则只返回纯文本500 Internal Server Error。对应测试见 recovery_test.go。

Martini Env：区分开发与生产环境

部分 Martini 处理器依赖全局变量martini.Env来区分开发/生产行为。在生产环境部署时，强烈建议设置环境变量MARTINI_ENV=production。

环境变量在包初始化时被读取（env.go）：

const ( Dev string = "development" Prod string = "production" Test string = "test" ) var Env = Dev func init() { setENV(os.Getenv("MARTINI_ENV")) Root, err = os.Getwd() ... }

要点：

• Env的默认值是"development"（测试Test_SetENV印证：空串时保持默认值）。
• 前面提到的Recovery中间件就是依据Env == Dev决定输出 HTML panic 页面还是纯文本 500。
• Root变量在初始化时记录当前工作目录，Static中间件处理相对目录时会filepath.Join(Root, directory)（见 static.go），因此相对路径是相对进程启动目录解析的。

与现有服务器集成：http.Handler 兼容

Martini 实例实现了http.Handler接口（ServeHTTP入口见 martini.go），因此可以轻松挂载到既有 Go 服务器的子树下。下面是一段可直接运行在 Google App Engine 上的 Martini 应用：

package hello import ( "net/http" "github.com/go-martini/martini" ) func init() { m := martini.Classic() m.Get("/", func() string { return "Hello world!" }) http.Handle("/", m) }

同理，你也可以在自己控制的http.Server中把 Martini 作为处理器传入，灵活掌控监听细节。

端口与主机配置

Martini 的Run函数会读取PORT和HOST两个环境变量来决定监听地址，两者都未设置时默认监听localhost:3000（Run() 实现）。

如果需要更灵活的端口/主机控制，改用RunOnAddr：

m := martini.Classic() // ... m.RunOnAddr(":8080")

RunOnAddr内部直接调用http.ListenAndServe(addr, m)，并在启动时打印listening on {addr} ({env})；若监听失败会以Fatalln退出。注意Run/RunOnAddr是阻塞调用，通常放在main末尾。

404 与错误处理

默认情况下，未匹配任何路由的请求会得到标准的 404 响应（NewRouter的默认 NotFound 栈是http.NotFound，见 router.go）。你可以自定义 NotFound 处理器，甚至叠加多个：

m.NotFound(func() string { return "not found" })

NotFound同样遵循返回值规范——返回字符串得到 200 + 文本，返回(int, string)则应用对应状态码（Test_NotFoundAsHandler中分别验证了 200 与 404 两种形态）。把静态文件的兜底处理挂在 NotFound 链上（见前文"服务默认文档"）是这套机制最经典的用法。

中间件生态：martini-contrib

社区围绕 Martini 建立了martini-contrib组织，提供了大量可直接使用的中间件，覆盖日常 Web 开发的大多数需求。以下为 README 中列出的代表性项目（按功能归类，仅保留名称与用途说明）：

• HTTP 解析类：acceptlang（解析Accept-Language请求头）、binding（把原始请求映射/校验到结构体）、encoder（多格式渲染与内容协商编码服务）、method（通过请求头或表单字段覆盖 HTTP 方法）、strip（URL 前缀剥离）、web（hoisie web.go 的 Context）。
• 认证授权类：auth（认证处理器）、oauth2（OAuth 2.0 登录，支持 Google、Facebook、GitHub）、permissions2（跟踪用户、登录状态与权限）、sessionauth（让路由需要登录，并在 Session 中处理用户登录）、vauth（厂商 Webhook 认证，当前支持 GitHub 与 TravisCI）。
• 安全类：accessflags（访问控制）、cors（跨域 CORS 支持）、csrf（CSRF 防护）、secure（若干快速安全加固）。
• 传输与日志类：gzip（请求 gzip 压缩）、gorelic（NewRelic 监控中间件）、logstasher（输出 logstash 兼容 JSON 日志）、throttle（请求速率限制）、staticbin（从二进制数据提供静态文件）。
• 模板渲染与会话类：render（轻松渲染 JSON 与 HTML 模板的服务）、sessions（Session 服务）、sessionauth（配合 sessions 实现登录态管理）。

关于实时热重载：README 提到gin与fresh两个社区工具都支持 Martini 应用的 live reload，开发时可配合使用，免去手动重启的麻烦。

结语

从这份指南可以看出，Martini 的核心设计极其简洁：一个实现了http.Handler的应用结构体、一个基于反射的依赖注入容器、一条"写入即短路"的处理器链，再加上一套把路由模式编译为正则的匹配器——四者组合便构成了完整、可扩展的模块化 Web 框架。尽管项目已停止维护，但它的源码（本仓库仅十余个 Go 文件）依然是学习 Go 中间件设计、依赖注入与路由引擎的绝佳教材。若要在存量项目中继续使用，建议结合上文的MARTINI_ENV=production配置、RunOnAddr端口控制与Fallback/Exclude静态文件策略做好生产化部署。

进一步阅读：仓库内 martini.go（应用与上下文）、router.go（路由引擎）、static.go（静态文件）、return_handler.go（返回值处理），以及配套的 router_test.go、static_test.go、martini_test.go 测试文件，均可作为深入理解本文各章节的源码入口；translations/README_zh_cn.md 提供了 README 的中文翻译版本可供对照。

• 后端