Go 源码之 gin 框架

// Engine的实例，包括了路由组，路由树，中间件和其他等一系列配置
type Engine struct {
  // 路由组
    RouterGroup

  // 如果当前路径无法匹配，但存在带有（不带有）尾斜杠的路径处理程序，RedirectTrailingFlash将启用自动重定向
  // 例如，如果请求了/foo/，但只有/foo的路由存在，则客户端将被重定向到/foo
  // GET请求的http状态代码为301，所有其他请求方法的http状态为307。
    RedirectTrailingSlash bool

    // RedirectFixedPath如果启用，如果没有为其注册句柄，则路由器将尝试 修复 当前请求路径。
  // 首先删除像../或//这样的多余路径元素。然后，路由器对清理后的路径进行不区分大小写的查找。如果可以找到该路由的句柄，则路由器对GET请求使用状态代码301，
  // 对所有其他请求方法使用状态代码307，重新定向到正确的路径。例如/FOO和/..//FOO可以重定向到/FOO。
  // RedirectTrailingFlash独立于此选项。
    RedirectFixedPath bool

  // HandleMethodNotAllowed如果启用，则如果当前请求无法路由，则路由器会检查当前路由是否允许其他方法。
  // 如果是这种情况，则使用“Method Not Allowed”和 HTTP状态代码405 回答请求。
  // 如果不允许其他方法，则将请求委托给NotFound处理程序。
    HandleMethodNotAllowed bool

    // ForwardedByClientIP（如果启用），将从与存储在“（*gin.Engine）.RemoteIPHeaders”中的标头匹配的请求标头解析客户端IP。
  // 如果未提取任何IP，它将返回到从“（*gin.Context）.Request.Remoddr”获取的IP。
    ForwardedByClientIP bool

    // AppEngine was deprecated.
    // Deprecated: USE `TrustedPlatform` WITH VALUE `gin.PlatformGoogleAppEngine` INSTEAD
    // #726 #755 If enabled, it will trust some headers starting with
    // 'X-AppEngine...' for better integration with that PaaS.
    AppEngine bool

    // UseRawPath if enabled, the url.RawPath will be used to find parameters.
  // UseRawPath（如果启用），url.RawPath将用于查找参数。
    UseRawPath bool

    // UnescapePathValues如果为true，则路径值将被取消转义。
    // 如果UseRawPath为false（默认情况下），则UnescapePathValues实际上为true，
    // 作为url。将使用路径，该路径已未被覆盖。
    UnescapePathValues bool

    // RemoveExtraSlash a parameter can be parsed from the URL even with extra slashes.
    // See the PR #1817 and issue #1644
    RemoveExtraSlash bool

    // RemoteIPHeaders list of headers used to obtain the client IP when
    // `(*gin.Engine).ForwardedByClientIP` is `true` and
    // `(*gin.Context).Request.RemoteAddr` is matched by at least one of the
    // network origins of list defined by `(*gin.Engine).SetTrustedProxies()`.
    RemoteIPHeaders []string

    // TrustedPlatform if set to a constant of value gin.Platform*, trusts the headers set by
    // that platform, for example to determine the client IP
    TrustedPlatform string

    // MaxMultipartMemory value of 'maxMemory' param that is given to http.Request's ParseMultipartForm
    // method call.
    MaxMultipartMemory int64

    // UseH2C enable h2c support.
    UseH2C bool

    // ContextWithFallback enable fallback Context.Deadline(), Context.Done(), Context.Err() and Context.Value() when Context.Request.Context() is not nil.
    ContextWithFallback bool

    delims           render.Delims
  // https://cloud.tencent.com/developer/article/1580456
    secureJSONPrefix string  
    HTMLRender       render.HTMLRender
  // FuncMap是定义从名称到函数的映射的映射类型。
  // 每个函数必须有一个返回值或两个返回值，其中第二个返回值具有类型错误。
  // 在这种情况下，如果在执行期间第二个（error）参数的计算结果为非nil，则执行终止，Execute返回该错误。
  // FuncMap在“text/template”中具有与FuncMap相同的基本类型，复制到此处，因此客户端无需导入“text/template”。
    FuncMap          template.FuncMap 

    trees            methodTrees // 请求的method数组，每个元素是一个前缀树

}

// 所有的http请求最终都会走这里
func (engine *Engine) ServeHTTP(w http.ResponseWriter, req *http.Request) {
    c := engine.pool.Get().(*Context) // 从池里取一个context
    c.writermem.reset(w) // 重置
    c.Request = req // 赋值请求
    c.reset() // 重置数据

    engine.handleHTTPRequest(c) // 核心处理函数

    engine.pool.Put(c) // 放回缓冲池
}
// 核心处理函数
func (engine *Engine) handleHTTPRequest(c *Context) {
  // 请求的Method类型，如GET等
    httpMethod := c.Request.Method
  // 请求的路径
    rPath := c.Request.URL.Path
    unescape := false
    if engine.UseRawPath && len(c.Request.URL.RawPath) > 0 {
        rPath = c.Request.URL.RawPath
        unescape = engine.UnescapePathValues
    }

    if engine.RemoveExtraSlash {
        rPath = cleanPath(rPath)
    }

    // 从methodTree中匹配method和请求url
    t := engine.trees
    for i, tl := 0, len(t); i < tl; i++ {
        if t[i].method != httpMethod {
            continue
        }
        root := t[i].root
        // 从前缀树methodTree中匹配到叶子节点value
        value := root.getValue(rPath, c.params, c.skippedNodes, unescape)
        if value.params != nil {
            c.Params = *value.params
        }
    // 执行中间件
        if value.handlers != nil {
            c.handlers = value.handlers
            c.fullPath = value.fullPath
            c.Next() // 依次从handlers数组中FIFO执行中间件
            c.writermem.WriteHeaderNow() // 最终写入http响应流responseWriter中
            return
        }
        if httpMethod != http.MethodConnect && rPath != "/" {
            if value.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 value := tree.root.getValue(rPath, nil, c.skippedNodes, unescape); value.handlers != nil {
                c.handlers = engine.allNoMethod
                serveError(c, http.StatusMethodNotAllowed, default405Body)
                return
            }
        }
    }
    c.handlers = engine.allNoRoute
    serveError(c, http.StatusNotFound, default404Body)
}

type methodTrees []methodTree

// 压缩前缀树，存储了http.Method的请求路径
type methodTree struct {
    method string
    root   *node
}
type node struct {
    path      string // 存储：共同的最长前缀字符
    indices   string
    wildChild bool
    nType     nodeType
    priority  uint32
    children  []*node // 有共同的最长前缀字符path的url path
    handlers  HandlersChain
    fullPath  string  // 叶子节点存储的是完整的请求路径
}
// 构建树的函数
func addRoute(){}

// gin.Context是gin框架中最重要的一部分
type Context struct {
    writermem responseWriter // 响应的数据流
    Request   *http.Request //  请求句柄
    Writer    ResponseWriter // 响应的Writer

    handlers HandlersChain // 中间件handler数组
    index    int8 // handler数组的下标，表示已经执行的下标
    fullPath string // 完整的url路径

    engine       *Engine
}

// 调用了handler，httpMethod=http.MethodGet，其他什么c.POST等都是差不多
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)
  // 将请求的handler和group的全局handler合并
    handlers = group.combineHandlers(handlers)
  // 添加路由到前缀树methodTree中
    group.engine.addRoute(httpMethod, absolutePath, handlers)
    return group.returnObj()
}
// 根据请求的method和path，构建前缀树methodTree
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")

    debugPrintRoute(method, path, handlers)

  // 从数组methodTrees中获取对应method的根节点
    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)

    // Update maxParams
    if paramsCount := countParams(path); paramsCount > engine.maxParams {
        engine.maxParams = paramsCount
    }

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

func (c *Context) JSON(code int, obj any) {
    c.Render(code, render.JSON{Data: obj})
}
// 将数据写入c.Writer，但是还没有响应http
func (c *Context) Render(code int, r render.Render) {
    c.Status(code)

    if !bodyAllowedForStatus(code) {
        r.WriteContentType(c.Writer)
        c.Writer.WriteHeaderNow()
        return
    }

    if err := r.Render(c.Writer); err != nil {
        panic(err)
    }
}