ctx.Locals是Fiber中唯一安全的请求级数据传递方式,线程安全、生命周期绑定请求、自动清空;不可用全局变量、闭包或context.WithValue替代,业务数据必须走Locals,超时控制等才用c.Context()。

别用全局变量管理请求级状态,Fiber 中唯一安全的上下文传值方式是 ctx.Locals —— 其他所有方案(context.WithValue、闭包、全局 map)在高并发下必然出错。
为什么不能用全局变量或 context.WithValue
Go 的 goroutine 复用机制会让上一个请求残留的数据被下一个请求读到。比如中间件里写 var userID int 再赋值,下一个请求进来时可能直接拿到上个用户的 ID。更隐蔽的问题是:c.Context() 返回的是 fasthttp 原生的 context.Context,它只用于超时/取消信号,**不是业务数据容器**;往里面塞 value 后,handler 里用 c.Locals 根本取不到,因为这是两个完全独立的存储空间。
常见翻车场景:
- 中间件调
c.Context().WithValue("user", u),handler 里写c.Locals("user")→ 返回nil - 多个 goroutine 并发写同一个全局 map → panic 或数据错乱
- 忘记清空,导致内存泄漏或跨请求污染
ctx.Locals 的正确用法和限制
ctx.Locals 是 Fiber 专为单次请求设计的线程安全存储,底层是 map[string]any + sync.RWMutex,且随请求结束自动清空。存取方式简单:
ctx.Locals("user_id", 123) 存,ctx.Locals("user_id").(int) 取(需类型断言)。
注意事项:
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器,提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象,支持命名依赖等
- 存结构体指针比存值更高效:
ctx.Locals("user", &user),避免大对象拷贝 - 不支持嵌套 key(如
"auth.role"),要用结构体字段代替 - 禁止存
channel、sync.Mutex、goroutine 句柄等非序列化类型,会 panic - 不能当缓存用:不支持 TTL、不跨请求复用、不持久化
异步任务中怎么安全传递 Locals 数据
一旦启动 goroutine 或投递消息队列任务,原始 ctx 已结束,Locals 不可访问。直接传 c 进去,轻则 panic,重则读到随机内存值。
必须显式提取再传参:
userID := c.Locals("user_id").(int)
go func(id int) {
log.Printf("processing user %d", id)
}(userID)
如果用第三方异步库(如 asynq),关键字段(租户 ID、trace ID)必须手动塞进任务 payload;日志打点也得提前取好值,别在 goroutine 里调 c.Locals。
哪些场景该用 c.Context() 而不是 Locals
c.Context() 唯一合法用途是透传超时与取消信号,比如传给数据库查询或 HTTP 客户端:
db.QueryRowContext(c.Context(), "SELECT ...") client.Do(ctx, req, resp)
切忌把 Locals 数据“同步”过去——既没必要,还可能被下游库误读。业务数据一律走 Locals,控制流信号才走 c.Context()。这点混淆是线上故障最常被忽略的根源。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!










