Gin核心源码解析

Gin 是一个轻量级 web 框架，具有简洁、易用、高效等特性，是目前 Go 开源社区最火热的项目之一。

ps: 默认读者有一定的 Go 基础，本文将只对 Gin 核心数据结构、处理流程进行介绍。

Engine

func main() {
	r := gin.Default()

    // 127.0.0.1:8080/ping pong
	r.GET("/ping", func(ctx *gin.Context) {
		ctx.JSON(http.StatusOK, "pong")
	})

	r.Run()
}

一切都将开始于一个最简单的 demo 程序。其中我们通过 gin.Default()获取了一个*gin.Engine对象，我们通过追踪这个函数取查看下这个对象的结构。排除掉一些功能配置参数后，谨慎下如下三个核心结构。

type Engine struct {
    // 路由组
	RouterGroup
    ...
    // contex复用池
	pool             sync.Pool
    // 每一个http method 的基于radix的路由树
	trees            methodTrees
	...
}

RouterGroup

type RouterGroup struct {
	Handlers HandlersChain
	basePath string
	engine   *Engine
	root     bool
}

RouterGroup 是我们使用路由组时直接相关的一个数据结构。

func (group *RouterGroup) Group(relativePath string, handlers ...HandlerFunc) *RouterGroup {
	return &RouterGroup{
		Handlers: group.combineHandlers(handlers),
		basePath: group.calculateAbsolutePath(relativePath),
		engine:   group.engine,
	}
}

Handlers 是我们通过Group方法注册的全量公共中间件，使用 copy 的方式进行装载（早期使用 append），数量最多 63 个，由const abortIndex int8 = math.MaxInt8 >> 1决定。

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

basePath 是路由访问的全量路径。
engine 为指向我们创建的 Engine 实例的指针。在New函数中指定。

sync.Pool

go 提供的是一个临时对象存储池，这里暂时不做详细介绍，可以大致看看其结构。
相关解析文档已经更新至于此处。

type Pool struct {
	noCopy noCopy

	local     unsafe.Pointer // local fixed-size per-P pool, actual type is [P]poolLocal
	localSize uintptr        // size of the local array

	victim     unsafe.Pointer // local from previous cycle
	victimSize uintptr        // size of victims array

	// New optionally specifies a function to generate
	// a value when Get would otherwise return nil.
	// It may not be changed concurrently with calls to Get.
	New func() any
}

methodTrees

type methodTrees []methodTree

type methodTree struct {
	method string // 方法
	root   *node // radix树根
}

type node struct {
	path      string
	indices   string
	wildChild bool
	nType     nodeType
	priority  uint32
	children  []*node // child nodes, at most 1 :param style node at the end of the array
	handlers  HandlersChain
	fullPath  string
}

每一个 http 方法都会创建一个对应的路由树(压缩前缀树，基数树)。基数树结构大致如下:

压缩前缀树的每一个节点都会保存其所有子节点的公共最长前缀。如图左侧分支存储app、apple、application三个单词。

path 保存最长公共前缀
indices 为子树的索引
wildChild 子节点包含通配符标记
nType 节点类型
priority 优先级额，配合 indeces 构建索引使用，每多一个子节点增加一
children []*node 子节点，:param节点排在最后，根据 prority 进行排序
handlers 同 Group 中类似，保存全量中间件和处理函数
fullPath 全量路径

执行流程

Default

func Default(opts ...OptionFunc) *Engine {
	debugPrintWARNINGDefault()
	engine := New()
	engine.Use(Logger(), Recovery()) // 加载默认中间件
	return engine.With(opts...) // 处理用户配置
}

debugPrintWARNINGDefault() 如果使用 Debug 模式则会答应警告信息，包括 go 版本是否适配，加载 recover 和 logger 中间件提示。

New

func New(opts ...OptionFunc) *Engine {
	debugPrintWARNINGNew()
	engine := &Engine{
		RouterGroup: RouterGroup{ // 创建总的路由组
			Handlers: nil,
			basePath: "/",
			root:     true,
		},
		FuncMap:                template.FuncMap{},
		RedirectTrailingSlash:  true,
		RedirectFixedPath:      false,
		HandleMethodNotAllowed: false,
		ForwardedByClientIP:    true,
		RemoteIPHeaders:        []string{"X-Forwarded-For", "X-Real-IP"},
		TrustedPlatform:        defaultPlatform,
		UseRawPath:             false,
		RemoveExtraSlash:       false,
		UnescapePathValues:     true,
		MaxMultipartMemory:     defaultMultipartMemory,
		trees:                  make(methodTrees, 0, 9), // 开辟九种方法的树根空间
		delims:                 render.Delims{Left: "{{", Right: "}}"},
		secureJSONPrefix:       "while(1);",
		trustedProxies:         []string{"0.0.0.0/0", "::/0"},
		trustedCIDRs:           defaultTrustedCIDRs,
	}
	engine.RouterGroup.engine = engine // 为路由组加载gin Engine
	engine.pool.New = func() any { // 初始化context池
		return engine.allocateContext(engine.maxParams)
	}
	return engine.With(opts...) // 处理用户配置
}

Group

介绍路由组结构时已经介绍过了，比较简单的一个过程。

Get

创建 Get 方法路由，其他方法于此类似这里就至追踪 Get 这一个方法。

func (group *RouterGroup) GET(relativePath string, handlers ...HandlerFunc) IRoutes {
	return group.handle(http.MethodGet, relativePath, handlers)
}

func (group *RouterGroup) handle(httpMethod, relativePath string, handlers HandlersChain) IRoutes {
	absolutePath := group.calculateAbsolutePath(relativePath) // 计算全量路径
	handlers = group.combineHandlers(handlers) // 合并处理函数
	group.engine.addRoute(httpMethod, absolutePath, handlers)
	return group.returnObj()
}

func (engine *Engine) addRoute(method, path string, handlers HandlersChain) {
    // 一些参数检测函数
	assert1(path[0] == '/', "path must begin with '/'")
	assert1(method != "", "HTTP method can not be empty")
	assert1(len(handlers) > 0, "there must be at least one handler")
    // debug模式下的的影响下
	debugPrintRoute(method, path, handlers)
    // 获取对应方法的路由树根节点 没有则新建
	root := engine.trees.get(method)
	if root == nil {
		root = new(node)
		root.fullPath = "/"
		engine.trees = append(engine.trees, methodTree{method: method, root: root})
	}
	root.addRoute(path, handlers)
    // 更新最大参数标记
	if paramsCount := countParams(path); paramsCount > engine.maxParams {
		engine.maxParams = paramsCount
	}

	if sectionsCount := countSections(path); sectionsCount > engine.maxSections {
		engine.maxSections = sectionsCount
	}
}

添加路由的过程有点点复杂，就可以结合流程图查看。分支结构比较多。。。

func (n *node) addRoute(path string, handlers HandlersChain) {
	fullPath := path
	n.priority++  // 增加权重

	// 空树直接插入
	if len(n.path) == 0 && len(n.children) == 0 {
		n.insertChild(path, fullPath, handlers)
		n.nType = root
		return
	}

	parentFullPathIndex := 0

walk:
	for {
		// 寻找最长公共前缀，不包含 : 和 *
		i := longestCommonPrefix(path, n.path)

		// 如果公共前缀比当前路径短 则需要拆分节点
		if i < len(n.path) {
            // 创建新的子节点
			child := node{
				path:      n.path[i:],
				wildChild: n.wildChild,
				nType:     static,
				indices:   n.indices,
				children:  n.children,
				handlers:  n.handlers,
				priority:  n.priority - 1,
				fullPath:  n.fullPath,
			}

			n.children = []*node{&child}
			// 跟新原节点信息
			n.indices = bytesconv.BytesToString([]byte{n.path[i]})
			n.path = path[:i]
			n.handlers = nil
			n.wildChild = false
			n.fullPath = fullPath[:parentFullPathIndex+i]
		}

		// 公共节点长于路由路径  截除公共路径
		if i < len(path) {
			path = path[i:]
			c := path[0]

			// 参数结点后的 /
			if n.nType == param && c == '/' && len(n.children) == 1 {
				parentFullPathIndex += len(n.path)
				n = n.children[0]
				n.priority++
				continue walk
			}

			// 查看是否有前缀匹配的孩子节点
			for i, max := 0, len(n.indices); i < max; i++ {
				if c == n.indices[i] {
					parentFullPathIndex += len(n.path)
					i = n.incrementChildPrio(i)
					n = n.children[i]
					continue walk
				}
			}

			// 路由是不是完全匹配
			if c != ':' && c != '*' && n.nType != catchAll {
                // 注册索引
				n.indices += bytesconv.BytesToString([]byte{c})
				child := &node{
					fullPath: fullPath,
				}
				n.addChild(child)
                // 调整有先级
				n.incrementChildPrio(len(n.indices) - 1)
				n = child
			} else if n.wildChild { // 孩子节点包含通配符
				// 插入通配符结点时需要判读是否有冲突
				n = n.children[len(n.children)-1]
				n.priority++

				// 判断通配符是否匹配
				if len(path) >= len(n.path) && n.path == path[:len(n.path)] &&
					// 不能为全部或结点添加子节点
					n.nType != catchAll &&
					// 检查通配长度结点路径更长 e.g. :name and :names
					(len(n.path) >= len(path) || path[len(n.path)] == '/') {
					continue walk
				}

				// 通配符冲突
				pathSeg := path
				if n.nType != catchAll {
					pathSeg = strings.SplitN(pathSeg, "/", 2)[0]
				}
				prefix := fullPath[:strings.Index(fullPath, pathSeg)] + n.path
				panic("'" + pathSeg +
					"' in new path '" + fullPath +
					"' conflicts with existing wildcard '" + n.path +
					"' in existing prefix '" + prefix +
					"'")
			}

            // 处理完所有特殊情况后执行插入操作
			n.insertChild(path, fullPath, handlers)
			return
		}

		// 向当前结点插入方法
		if n.handlers != nil {
			panic("handlers are already registered for path '" + fullPath + "'")
		}
        // 注册处理方法
		n.handlers = handlers
		n.fullPath = fullPath
		return
	}
}

本文作者： Tiny Beer
本文链接： https://tinybeer.github.io/2024/05/28/Gin核心源码解析/
版权声明： 本博客所有文章除特别声明外，均采用 MIT 许可协议。转载请注明出处！