Pure - 小而美的JSON Web API框架

一. 什么是Pure

Pure是Go语言实现的，小而美的Web API框架。在设计上它提供纯粹的JSON支持：所有的API调用都通过GET或者POST请求来实现，请求参数和响应的结果都按照JSON格式进行打包。

除此之外，Pure框架还支持插件式开发，开发者通过开发各种中间件插件来扩展更多可定制的功能。框架通过中间件提供原生支持的功能有：

1. pure.CORSMiddleware：处理CORS请求；
2. pure.JSONMiddleware：检查HTTP请求头是否为application/json；
3. pure.MultipartFormMiddleware：检查HTTP请求头是否为multipart/form-data；
4. pure.LoggerMiddleware：记录请求日志，包含请求的处理时间，单位毫秒（ms）；
5. pure.RecoverPanicMiddleware：业务逻辑发生崩溃时恢复。

RESTful API的设计方式是通过HTTP方法来规范对资源的操作：

• 使用GET获取资源
• 使用POST创建资源
• 使用PUT更新现有资源
• 使用DELETE删除现有资源

而Pure框架采用的Pure-JSON设计方式则是通过URL命名来规范对资源的操作。虽然不是硬性要求，但强烈建议按照CRUD来进行命名：

• Create：创建资源
• Retrieve：获取资源
• Update：更新现有资源
• Delete：删除现有资源

二. 定义API

使用Pure框架开发API，需要定义三种结构：请求参数，处理逻辑（Handler）和响应结果。然后我们将该处理逻辑注册到框架中即可。下面我们通过一个Hello API举例说明一下。假设该API需要一个请求参数name，业务逻辑是返回一句问候语“hello xxx”。那么我们可以通过以下三个步骤完成。

1. 定义请求参数和响应结果

分别定义一个helloReq和helloRsp的结构，添加JSON tag：

type helloReq struct {
  Name string `json: "name"`
}
type helloRsp struct {
  Greeting string `json:"greeting"`
}

2. 定义处理逻辑

所有的处理逻辑必须定义在Handle(Context) interface{}函数中，即具体的处理逻辑一定满足pure.Handler接口：

type helloHandler struct {
  req helloReq
}
func (h helloHandler) Handle(ctx context.Context) interface{} {
  return helloRsp{ Greeting: fmt.Sprintf("hello %s", h.req.Name) }
}

3. 注册处理逻辑

最后，将处理逻辑注册到Pure框架中即可：

pure.API().
  Version(1).
  Class("hello").
  URI("hello").
  Post().
  Handle(helloHandler{}).
  Use(pure.LoggerMiddleware, pure.JSONMiddleware).
  Final()

此时客户端通过POST请求http://host/api_1/hello/hello即可获得相应的调用结果。

4. 实现原理

Pure框架通过上述“链式调用”构造了一个API对象（建造者模式），然后将这个对象注册到系统中。当有新web请求到达时，根据HTTP方法（GET或者POST）会回调到不同的分配函数中（getDispatcher或postDispatcher）。这两个处理函数执行一套相似的逻辑：根据URL获取用户注册的handler类型，然后使用Go语言的反射机制运行时构造该handler，初始化请求参数，并调用该处理逻辑，然后将返回的结果发送给请求方。

三. 插件式中间件开发

除了上面提供的中间件外，开发者还可以自行开发更多的插件来满足业务逻辑的需要。一般来说，开发中间件的基本套路就是在业务逻辑开始处理之前截获请求，然后在真正业务逻辑执行之前或之后进行其他处理，或者在开始处理业务逻辑之前进行必要检查，如不满足要求则进一步选择处理或者不处理。比如要实现一个记录请求日志的中间件插件，则需要在业务逻辑执行之前记录时间，然后运行业务逻辑，最后再减去之间记录的时间得到业务逻辑执行时间，然后打印日志，如下：

func LoggerMiddleware(w http.ResponseWriter, r *http.Request, next http.HandlerFunc) {
    start := time.Now()

    rw := NewResponseWriter(w)
    next(rw, r)

    logging := fmt.Sprintf("%s -- %v %s %s %s %s - %s %v",
        r.RemoteAddr,
        start,
        r.Method,
        r.URL.Path,
        r.Proto,
        http.StatusText(rw.StatusCode()),
        r.Header.Get("User-Agent"),
        time.Since(start))

    holmes.Infoln(logging)
}

更多的中间件例子请参考源代码。