Gin的基本使用

Gin是一个比较轻量级的http框架，主要是提供了几个便于使用的功能：

• 简单的中间件注册，可以很方便的实现通用中间件的使用注册
• 提供了比较方便和全面的路由注册，方便的实现RESTful接口的实现
• 提供了便捷的获取参数的方法，包括get、post兵可以可以把数据直接转换成对象
• 对路由的分组，Gin可以对一组路由做统一的中间件注册等操作
• 可以手机所有错误，统一在统一的地方写日志

性能方面：

• 是路由的基础数据格式为基数树没有使用反射，所以性能方面也是比较低消耗内存低
• 上下文context使用了对象池，fasthttp中也同样使用了sync.pool

使用方便也是比较简单的，下面有一个很简单的例子

package main

import (
    "fmt"
    "github.com/gin-gonic/gin"
    "test/gin/middleware/model"
)

func main() {
    //创建router
    router := gin.Default()
    //创建组
    group := router.Group("/api")
    //为组加中间件
    group.Use(func(context *gin.Context) {
        fmt.Println("api group url:", context.Request.URL.String())
    })
    //为组加路由方法
    group.GET("/test", func(context *gin.Context) {
        context.JSON(200, model.Message{Message:"ok"})
    })
    //运行
    router.Run(":3333")
}

例子中是一个最简单的Gin框架的应用。创建了一个engine，创建了组并且为组添加了中间件之后在这个group下的路由方法都将使用这个中间件，方便对api最系统的管理对不同的api做不同的处理。
在Terminal中访问可以看到下面的结果

curl http://localhost:3333/api/test
{"Message":"ok"}panleiMacBook-Pro:test 

主要流程的源码

首先我们先看例子中的gin.Default() 返回的engine对象，这是Gin的主要对象。只对最主要的属性加了注释

type Engine struct {
    //路由组
    RouterGroup
    RedirectTrailingSlash bool
    RedirectFixedPath bool
    HandleMethodNotAllowed bool
    ForwardedByClientIP    bool
    AppEngine bool
    UseRawPath bool
    UnescapePathValues bool
    MaxMultipartMemory int64
    delims           render.Delims
    secureJsonPrefix string
    HTMLRender       render.HTMLRender
    FuncMap          template.FuncMap
    allNoRoute       HandlersChain
    allNoMethod      HandlersChain
    noRoute          HandlersChain
    noMethod         HandlersChain
    // 对象池 用来创建上下文context
    pool             sync.Pool
    //记录路由方法的 比如GET POST 都会是数组中的一个 每个方法对应一个基数树的一个root的node
    trees            methodTrees
}

然后我们来看Default方法，其实很简单就是创建一个engine对象并且添加默认的两个中间件，一个是做log显示，显示每次请求可以再console中看到。每次创建engine对象的时候回默认的添加一个routergroup地址为默认的”/” 代码如下：

func Default() *Engine {
    debugPrintWARNINGDefault()
    engine := New()
    engine.Use(Logger(), Recovery())
    return engine
}
//new方法中默认的 添加了routergroup路由 “/”
func New() *Engine {
    debugPrintWARNINGNew()
    engine := &Engine{
        RouterGroup: RouterGroup{
            Handlers: nil,
            basePath: "/",
            root:     true,
        },
        FuncMap:                template.FuncMap{},
        RedirectTrailingSlash:  true,
        RedirectFixedPath:      false,
        HandleMethodNotAllowed: false,
        ForwardedByClientIP:    true,
        AppEngine:              defaultAppEngine,
        UseRawPath:             false,
        UnescapePathValues:     true,
        MaxMultipartMemory:     defaultMultipartMemory,
        trees:                  make(methodTrees, 0, 9),
        delims:                 render.Delims{Left: "{{", Right: "}}"},
        secureJsonPrefix:       "while(1);",
    }
    engine.RouterGroup.engine = engine
    engine.pool.New = func() interface{} {
        return engine.allocateContext()
    }
    return engine
}

在看中间件之前还有一个重要的对象context 上下文对象
这个对象中存放了 engine指针、请求的request对象、返回的responsewriter对象还有一些参数等对象，这个context将在请求一开始就被创建一直贯穿整个执行过程，包括中间件，路由等。最后的返回值可以再responseWriter写，最终就会返回给客户端。

type Context struct {
    writermem responseWriter
    Request   *http.Request
    Writer    ResponseWriter

    Params   Params
    handlers HandlersChain
    index    int8

    engine *Engine

    // Keys is a key/value pair exclusively for the context of each request.
    Keys map[string]interface{}

    // Errors is a list of errors attached to all the handlers/middlewares who used this context.
    Errors errorMsgs

    // Accepted defines a list of manually accepted formats for content negotiation.
    Accepted []string
}

接下来看得是添加中间件use方法

func (engine *Engine) Use(middleware ...HandlerFunc) IRoutes {
    //调用routegroup的use方法
    engine.RouterGroup.Use(middleware...)
    engine.rebuild404Handlers()
    engine.rebuild405Handlers()
    return engine
}

func (group *RouterGroup) Use(middleware ...HandlerFunc) IRoutes {
    //为group的handlers添加中间件 
    group.Handlers = append(group.Handlers, middleware...)
    return group.returnObj()
}

添加为中间件之后就是添加正常路由，Gin中提供了GET、POST、DELETE更各种方法，我们就只看get方法其余的都是相同的处理方式。总结下来就是把group和传入的handler合并，并且计算出路径存入到tree中等客户端的调用。

func (group *RouterGroup) GET(relativePath string, handlers ...HandlerFunc) IRoutes {
    //调用get方法
    return group.handle("GET", relativePath, handlers)
}

func (group *RouterGroup) handle(httpMethod, relativePath string, handlers HandlersChain) IRoutes {
    //计算路径地址，比如group地址是 router.Group("/api")
    //结果为/api/test/ 就是最终计算出来的结果 使用path.join 方法拼接 其中加了一些判断
    absolutePath := group.calculateAbsolutePath(relativePath)
    //把group中的handler和传入的handler合并 
    handlers = group.combineHandlers(handlers)
    //把方法 路径 和处理方法作为node 加入到基数树种，基数树在下次单独学习分析
    group.engine.addRoute(httpMethod, absolutePath, handlers)
    return group.returnObj()
}

func (group *RouterGroup) combineHandlers(handlers HandlersChain) HandlersChain {
    finalSize := len(group.Handlers) + len(handlers)
    if finalSize >= int(abortIndex) {
        panic("too many handlers")
    }
    mergedHandlers := make(HandlersChain, finalSize)
    copy(mergedHandlers, group.Handlers)
    copy(mergedHandlers[len(group.Handlers):], handlers)
    return mergedHandlers
}

最后我们需要看run方法，之前的都是准备工作或者说是设置路由中间件。等run方法执行的时候则是服务真正启动起来。 代码很简单，几乎不需要注释是调用gohttp包的ListenAndServe方法把engine传入然后http包中会有一个for逻辑不停的监听这个端口号的所有请求。

func (engine *Engine) Run(addr ...string) (err error) {
    defer func() { debugPrintError(err) }()

    address := resolveAddress(addr)
    debugPrint("Listening and serving HTTP on %s\n", address)
    err = http.ListenAndServe(address, engine)
    return
}

func ListenAndServe(addr string, handler Handler) error {
    server := &Server{Addr: addr, Handler: handler}
    return server.ListenAndServe()
}

那么客户端最终请求之后会走到那些代码，又是怎么找到路由并且调用一个个中间件的呢？其实engine是继承了Handler 这个接口（可以看下面代码），我们知道如果不适用Gin框架直接使用http包我们所有的路由就是直接继承这个接口所以对这个接口我们是很熟悉的。
下面的serveHTTP 就是Gin的方法 最主要流程就是从tree中获取到路由，然后依次执行handler最终处理完成返回给客户端。

type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

func (engine *Engine) ServeHTTP(w http.ResponseWriter, req *http.Request) {
    //从对象池中获取context对象，这就是最初我们看到的一种优化性能的一种方式
    c := engine.pool.Get().(*Context)
    //重置writer中的一些值
    c.writermem.reset(w)
    把request放到context中
    c.Request = req
    c.reset()
    //调用处理方法
    engine.handleHTTPRequest(c)
    //处理完成把context对象放回到对象池
    engine.pool.Put(c)
}

func (engine *Engine) handleHTTPRequest(c *Context) {
    //获取请求方法和路径
    httpMethod := c.Request.Method
    path := c.Request.URL.Path
    unescape := false
    if engine.UseRawPath && len(c.Request.URL.RawPath) > 0 {
        path = c.Request.URL.RawPath
        unescape = engine.UnescapePathValues
    }

    //根据基数树的特性寻找方法发 并调用next方法 依次执行handler
    t := engine.trees
    for i, tl := 0, len(t); i < tl; i++ {
        if t[i].method != httpMethod {
            continue
        }
        root := t[i].root
        // Find route in tree
        handlers, params, tsr := root.getValue(path, c.Params, unescape)
        if handlers != nil {
            c.handlers = handlers
            c.Params = params
            c.Next()
            c.writermem.WriteHeaderNow()
            return
        }
        if httpMethod != "CONNECT" && path != "/" {
            if tsr && engine.RedirectTrailingSlash {
                redirectTrailingSlash(c)
                return
            }
            if engine.RedirectFixedPath && redirectFixedPath(c, root, engine.RedirectFixedPath) {
                return
            }
        }
        break
    }

    if engine.HandleMethodNotAllowed {
        for _, tree := range engine.trees {
            if tree.method == httpMethod {
                continue
            }
            if handlers, _, _ := tree.root.getValue(path, nil, unescape); handlers != nil {
                c.handlers = engine.allNoMethod
                serveError(c, http.StatusMethodNotAllowed, default405Body)
                return
            }
        }
    }
    c.handlers = engine.allNoRoute
    serveError(c, http.StatusNotFound, default404Body)
}

总结

从上面的流程我们可以看到，其实Gin框架就是对go http包的一次封装，加入了group和tree。让我们可以更简单方便的使用http包。其实Gin还有很多其他功能的源码包括参数分析 json解析等等，这次学习的只是Gin的主要流程。Gin中tree是一个亮点，是的它在查找路由性能方面有很大的优势，下一篇文章会主要学习tree（基数树）。