基于Gin框架的用户操作行为留痕系统-Golang-PHP中文网

gin 的 context 是行为留痕的唯一可靠载体，因其无全局 request 对象，所有请求数据仅存于 *gin.context 实例中，且生命周期与请求绑定，需通过 c.set/c.get 跨中间件传递并显式提取字段。

基于gin框架的用户操作行为留痕系统

为什么 Gin 的 Context 是行为留痕的唯一可靠载体

因为 Gin 没有全局 request 对象，所有请求生命周期内的数据（如 IP、路径、参数、耗时、用户 ID）只存在于 *gin.Context 实例中。一旦 handler 函数返回，c 就被回收，不在此刻提取并透传，后续中间件或日志写入就拿不到原始上下文。

常见错误是：在日志中间件里只记了 c.Request.URL.Path，却漏掉 c.ClientIP() 或未调用 c.Get("user_id") —— 后者往往由鉴权中间件注入，但若没显式 c.Set() 过，c.Get() 返回 nil 且不报错，导致留痕字段为空。

必须在鉴权中间件中用 c.Set("user_id", uid) 显式存入，不能依赖闭包变量或全局 map
c.Keys 是线程安全的 map，但仅限当前请求生命周期；跨中间件传递必须靠它，不能靠函数参数传参
避免在 handler 里直接 fmt.Println 打印行为，那不属于“留痕”——留痕指可结构化入库/落盘的数据

如何用中间件统一采集基础行为字段

不要每个接口都手写 c.ClientIP()、c.Request.Method 等，而是用一个中间件集中提取、挂载、透传。

示例代码片段：

Gin框架 1.9.0

Gin框架 1.9.0版本源码包下载，版本号 1.9.0，适合需要 sonic JSON 支持、路由修复和内容协商改进的 Go Web 开发场景。

下载

func TraceMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 提前记录起始时间
        start := time.Now()

        // 提取基础字段
        c.Set("trace_ip", c.ClientIP())
        c.Set("trace_method", c.Request.Method)
        c.Set("trace_path", c.Request.URL.Path)
        c.Set("trace_query", c.Request.URL.RawQuery)
        c.Set("trace_user_agent", c.Request.UserAgent())

        // 继续执行后续 handler
        c.Next()

        // 请求结束时补充字段
        c.Set("trace_status", c.Writer.Status())
        c.Set("trace_cost_ms", time.Since(start).Milliseconds())
    }
}

注意：c.Writer.Status() 必须在 c.Next() 之后调用，否则返回 0
c.Request.URL.RawQuery 比 c.Request.URL.Query() 更可靠，后者会自动 decode，可能破坏原始查询字符串格式
该中间件应放在鉴权中间件之后、业务 handler 之前，确保 user_id 已注入

绑定用户身份后如何安全扩展留痕字段

用户登录态通常由 JWT 或 session 中间件解析并写入 c，但直接从 token 解析出的 user_id 若未校验签名或过期，会导致留痕数据不可信。

正确做法是：在鉴权中间件中完成校验，并只写入已验证字段：

func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        tokenString := c.GetHeader("Authorization")
        if tokenString == "" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing token"})
            return
        }

        claims := jwt.MapClaims{}
        _, err := jwt.ParseWithClaims(tokenString, claims, func(t *jwt.Token) (interface{}, error) {
            return []byte("your-secret-key"), nil
        })
        if err != nil {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
            return
        }

        // ✅ 只写入可信字段
        c.Set("user_id", uint(claims["user_id"].(float64)))
        c.Set("user_role", claims["role"].(string))
        c.Next()
    }
}

不要在 trace 中间件里重复解析 token，性能差且易出错
c.Set("user_id", ...) 和 c.Set("user_role", ...) 必须在 c.Next() 前完成，否则业务 handler 可能读不到
若使用数据库查用户信息，建议只存 ID，详情由异步任务补全，避免阻塞主链路

留痕数据落地时容易忽略的兼容性问题

留痕最终要写入 MySQL / Kafka / ES，但 Gin 的 context 本身不序列化，直接 json.Marshal(c) 会 panic —— 因为 *gin.Context 包含不可序列化的字段（如 http.ResponseWriter）。

必须手动构造结构体提取所需字段：

type BehaviorLog struct {
    IP         string  `json:"ip"`
    Method     string  `json:"method"`
    Path       string  `json:"path"`
    UserID     uint    `json:"user_id,omitempty"`
    Role       string  `json:"role,omitempty"`
    Status     int     `json:"status"`
    CostMS     float64 `json:"cost_ms"`
    Timestamp  int64   `json:"timestamp"`
}

func BuildBehaviorLog(c *gin.Context) BehaviorLog {
    return BehaviorLog{
        IP:        c.GetString("trace_ip"),
        Method:    c.GetString("trace_method"),
        Path:      c.GetString("trace_path"),
        UserID:    c.GetUint("user_id"),
        Role:      c.GetString("user_role"),
        Status:    c.GetInt("trace_status"),
        CostMS:    c.GetFloat64("trace_cost_ms"),
        Timestamp: time.Now().UnixMilli(),
    }
}