ctx.Values() 是 Iris 中唯一安全的请求级数据传递方式,基于 sync.Map 实现线程安全、请求绑定且自动清理,禁止使用全局变量、context.WithValue 或结构体字段存储请求数据。

Context.Values() 是唯一安全的请求级数据传递方式
在 Iris 中,ctx.Values() 是为当前 HTTP 请求生命周期内共享数据设计的唯一正确载体。它底层用 sync.Map 实现,线程安全,且与请求绑定——请求结束自动清理,不会跨请求泄漏。别试图用全局变量、闭包或结构体字段存用户 ID、租户 ID 或认证状态,那些都会引发并发 bug 或上下文污染。
常见错误现象:在中间件里把 userID 赋值给某个包级变量,然后控制器里直接读取;结果高并发下 A 用户的 ID 被 B 用户的请求覆盖,返回错数据。
- 中间件中写入必须用
ctx.Values().Set("user_id", 123),不能用context.WithValue手动替换整个 context - 控制器中读取必须用
ctx.Values().Get("user_id"),类型断言后使用 - 不要往
Values()里塞大对象(如完整用户结构体),只放关键 ID 或轻量标识;大对象建议查完缓存后按需加载
为什么不能用 context.WithValue 替换原始 context
Iris 的 iris.Context 是封装好的接口,内部已持有 request-scoped context。你调用 c.Request.Context() 拿到的是底层 net/http 的 context,但 Iris 并不把它作为主上下文源;所有内置方法(如 ReadJSON、Params)都依赖 iris.Context 自己的状态管理。手动 context.WithValue(c.Request.Context(), key, val) 后,这个新 context 对 Iris 来说是“不可见”的,后续任何 Iris 方法都不会读取它。
容易踩的坑是:中间件里做了 req = req.WithContext(...),以为控制器能拿到,结果 ctx.Values().Get 返回 nil。
- 永远优先用
ctx.Values().Set/Get,这是 Iris 官方支持且测试覆盖的路径 -
context.WithValue只应在你明确要传给第三方库(比如数据库驱动、日志 SDK)时使用,并确保该库接收的是原始http.Request.Context() - 异步任务(
go func(){...}())中若需 tenant_id 等,必须显式传参或构造 isolatedCtx,不能依赖ctx.Values()
Values() 的 key 类型和命名冲突风险
ctx.Values().Set 的 key 是 interface{},但用字符串最安全。别用自定义 struct 或指针当 key——不同包里定义的同名 struct 在 Go 里是不同类型,会导致 Get 失败。
典型问题:鉴权中间件用 type userIDKey struct{} 当 key,而控制器里又定义了一个一模一样的 userIDKey,结果 Get 返回 nil,因为两个 struct 类型不等价。
- 统一用字符串 key,比如
"user_id"、"tenant_id"、"auth_scope" - 如果必须用类型安全 key,定义在公共包里导出,所有模块引用同一变量,例如
var UserIDKey = "user_id" - 避免 key 名重复:多个中间件都设
"id",后写的会覆盖前写的;建议加前缀,如"auth.user_id"、"tenant.id"
MVC 控制器里怎么安全获取 Values 数据
MVC 控制器方法签名中可以接收 iris.Context,但 Iris 不会自动把 Values() 里的内容绑定到结构体字段。你不能指望在 controller struct 里声明 UserID int `inject:"user_id"` 这类语法——Iris 没这机制。
必须显式调用 ctx.Values().Get() 并做类型断言。漏掉断言或忽略 nil 判断,运行时 panic 就等着你。
- 推荐写法:
if userID, ok := ctx.Values().Get("user_id").(int); ok { ... } - 更健壮写法:封装一个 helper 函数,如
GetUserID(ctx iris.Context) (int, bool),统一处理类型转换和默认值 - 不要在控制器 struct 的字段上加 tag 期望自动注入,那是 Gin 或某些 DI 框架的玩法,Iris MVC 不支持
真正容易被忽略的是:Values() 里的数据只活到当前请求结束,且完全不跨 goroutine。哪怕你在控制器里启动一个 go processAsync(ctx),那个新协程里 ctx.Values().Get 一定为空——这时候必须显式传参或用 context.WithValue 构造新 context 并传进去。
大量免费API接口:立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游,为数据API应用能力赋能!











