编辑“︁Gin上下文对象”︁（章节）

= Gin上下文对象 =

'''Gin上下文对象'''（通常称为<code>gin.Context</code>）是Gin框架中处理HTTP请求和响应的核心结构体。它封装了请求信息、响应方法、中间件处理等关键功能，是开发者与HTTP协议交互的主要接口。

== 概述 ==

Gin上下文对象（<code>*gin.Context</code>）在每次HTTP请求时被创建，并在请求生命周期中贯穿以下核心功能：
* 获取HTTP请求参数（路径参数、查询字符串、表单数据等）
* 处理HTTP响应（状态码、标头、JSON/XML等）
* 在中间件链中传递数据
* 控制请求处理流程（中止、重定向等）

<mermaid>
graph LR
    A[客户端请求] --> B[创建gin.Context]
    B --> C[中间件处理]
    C --> D[路由处理]
    D --> E[响应生成]
    E --> F[销毁Context]
</mermaid>

== 核心功能 ==

=== 请求数据获取 ===

==== 路径参数 ====
<syntaxhighlight lang="go">
// 路由定义
r.GET("/user/:name", func(c *gin.Context) {
    name := c.Param("name")  // 获取路径参数
    c.String(200, "Hello %s", name)
})

// 请求示例：GET /user/john
// 输出：Hello john
</syntaxhighlight>

==== 查询参数 ====
<syntaxhighlight lang="go">
r.GET("/search", func(c *gin.Context) {
    query := c.Query("q")          // 获取必须参数
    sort := c.DefaultQuery("sort", "asc")  // 带默认值
    
    c.JSON(200, gin.H{
        "query": query,
        "sort": sort,
    })
})

// 请求示例：GET /search?q=golang&sort=desc
// 输出：{"query":"golang","sort":"desc"}
</syntaxhighlight>

=== 响应处理 ===

==== JSON响应 ====
<syntaxhighlight lang="go">
r.GET("/api/info", func(c *gin.Context) {
    c.JSON(200, gin.H{
        "status":  "success",
        "version": "1.0.0",
    })
})

// 输出：
// HTTP/1.1 200 OK
// Content-Type: application/json
// 
// {"status":"success","version":"1.0.0"}
</syntaxhighlight>

==== 自定义标头 ====
<syntaxhighlight lang="go">
r.GET("/custom", func(c *gin.Context) {
    c.Header("X-Custom-Header", "Gin")
    c.String(200, "Headers set")
})
</syntaxhighlight>

== 数据传递 ==

Gin上下文允许在中间件和处理程序之间传递数据：

<syntaxhighlight lang="go">
// 中间件
authMiddleware := func(c *gin.Context) {
    if token := c.GetHeader("Authorization"); token != "" {
        c.Set("user", "authenticated_user")  // 存储数据
        c.Next()
    } else {
        c.AbortWithStatus(401)
    }
}

// 处理程序
r.GET("/profile", authMiddleware, func(c *gin.Context) {
    user, _ := c.Get("user")  // 获取数据
    c.String(200, "Welcome %s", user)
})
</syntaxhighlight>

== 流程控制 ==

=== 中止请求 ===
<syntaxhighlight lang="go">
r.GET("/admin", func(c *gin.Context) {
    if !isAdmin(c) {
        c.AbortWithStatusJSON(403, gin.H{"error": "Forbidden"})
        return
    }
    // 只有管理员能执行的代码...
})
</syntaxhighlight>

=== 重定向 ===
<syntaxhighlight lang="go">
r.GET("/old", func(c *gin.Context) {
    c.Redirect(301, "/new")
})
</syntaxhighlight>

== 实际案例 ==

=== RESTful API 实现 ===
<syntaxhighlight lang="go">
// 用户资源路由
api := r.Group("/api/v1")
{
    api.GET("/users", listUsers)
    api.POST("/users", createUser)
    api.GET("/users/:id", getUser)
    api.PUT("/users/:id", updateUser)
    api.DELETE("/users/:id", deleteUser)
}

func getUser(c *gin.Context) {
    id := c.Param("id")
    user, err := db.FindUser(id)
    if err != nil {
        c.JSON(404, gin.H{"error": "User not found"})
        return
    }
    c.JSON(200, user)
}
</syntaxhighlight>

== 高级特性 ==

=== 上下文超时控制 ===
<syntaxhighlight lang="go">
func slowHandler(c *gin.Context) {
    ctx := c.Request.Context()
    
    // 设置超时
    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()
    
    // 将新上下文绑定回Gin
    c.Request = c.Request.WithContext(ctx)
    
    // 执行长时间操作
    select {
    case <-time.After(3 * time.Second):
        c.String(200, "Done")
    case <-ctx.Done():
        c.String(504, "Timeout")
    }
}
</syntaxhighlight>

=== 自定义验证 ===
<syntaxhighlight lang="go">
type LoginForm struct {
    Username string `form:"username" binding:"required"`
    Password string `form:"password" binding:"required,min=6"`
}

r.POST("/login", func(c *gin.Context) {
    var form LoginForm
    if err := c.ShouldBind(&form); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    // 验证通过的处理...
})
</syntaxhighlight>

== 性能考虑 ==

Gin使用<code>sync.Pool</code>来重用上下文对象，显著减少GC压力。开发者应注意：
* 不要在上下文外保存<code>gin.Context</code>引用
* 大型数据应通过指针传递而非直接存储
* 中间件中完成资源清理

== 数学表示 ==

Gin上下文可以形式化表示为：
<math>
Context = (Request, Response, Metadata, MiddlewareStack)
</math>
其中：
* <math>Request = (Method, Path, Headers, Body)</math>
* <math>Response = (Status, Headers, Body)</math>
* <math>Metadata = \{key_1:value_1, ..., key_n:value_n\}</math>

== 总结 ==

Gin上下文对象是框架的核心抽象，提供了：
* 完整的请求/响应处理能力
* 中间件数据传递机制
* 流程控制方法
* 高效的内存管理

正确理解和使用上下文对象是开发高质量Gin应用的基础。

[[Category:后端框架]]
[[Category:Gin]]
[[Category:Gin基础]]