Iris 的 ctx 不能跨 goroutine 或 HTTP 调用传递，必须显式提取字段并注入新上下文；ctx.Values() 是唯一安全的请求内传参方式，取值需用类型安全方法，异步操作须提前抽值传参，出向调用须手动透传追踪头，中间件注册与 ctx.Next() 顺序不可错。
直接说结论：Iris 的 ctx 不能“传递”给其他 goroutine 或下游 HTTP 调用，必须显式提取关键字段（如 trace_id、tenant_id）再注入新上下文；原生 ctx.Request().Context() 是 Go 标准库 context，和 Iris 的 iris.Context 解耦，混用必丢值。
ctx.Values() 是唯一安全的请求内参数载体
Iris 中跨中间件、中间件到 handler 传参，只该用 ctx.Values().Set("key", value)。它绑定在当前请求生命周期内，线程安全、无需清理、不跨请求污染。
- 错误写法：
ctx.Set("user_id", 123)——ctx.Set方法根本不存在，编译不过 - 更危险的写法：
ctx.Request().Context().WithValue(...)—— 这个 context 和 Iris 的执行链完全无关，后续 handler 里ctx.Values()拿不到任何东西 - 取值务必用类型安全方法：
ctx.Values().GetInt64("user_id")或ctx.Values().GetString("trace_id")，别用interface{}强转，容易 panic - 结构体字段必须首字母大写（可导出），否则 JSON 序列化时为空
异步 goroutine 里 ctx.Values() 立刻失效
只要启动新 goroutine（go func() { ... }()），原 ctx 就不可用了。Go 的 context 不自动跨协程传播，这是最常被忽略的链路断裂点。
- Redis 缓存操作、Weaviate 向量写入、消息队列投递、定时任务触发——这些如果在 goroutine 里做，
ctx.Values().GetXXX()全是空或默认值 - 正确做法：提前把必要值抽出来，作为参数传入：
go processOrder(ctx.Values().GetString("tenant_id"), order) - 或者封装一个隔离 context：
isolatedCtx := context.WithValue(context.Background(), tenantKey, tenantID)，再传给 goroutine - 别存数据库连接、文件句柄等需手动释放的资源到
ctx.Values()—— 它不负责生命周期管理
HTTP 出向调用必须手动透传追踪头
Iris 的 http.Client（包括 iris.Context.DoHTTP）不感知 ctx，也不会自动带上 uber-trace-id 或 traceparent。链路在这里断掉，90% 的原因是忘了这一步。
- 先从当前 span 提取：
span := opentracing.SpanFromContext(ctx) - 再注入到 outbound 请求头：
tracer.Inject(span.Context(), opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(req.Header)) - 别用
http.DefaultClient，它没有上下文能力；推荐封装DoTracedRequest(ctx iris.Context, method, url string, body io.Reader) - 如果用了自定义 client，记得在
req = req.WithContext(...)之前完成 header 注入，顺序错了也无效
中间件注册顺序和 ctx.Next() 是硬性前提
即使代码全对，中间件没生效，ctx.Values().Set() 就等于没写。两个致命位置错误会直接让整个链路共享逻辑归零。
-
app.Use(mw)必须在所有app.Get()、app.Post()之前；写成app.Get("/x", h); app.Use(mw)→mw对/x完全不执行 - 分组路由同理：
api := app.Party("/api"); api.Use(jwtMw); api.Get("/me", h)，顺序错就白配 - 中间件函数末尾必须有
ctx.Next()，否则流程在中间件就终止，handler 根本不运行，自然看不到你设的值 - 别在中间件里
return早退，除非配合ctx.StopExecution()或ctx.StopWithStatus()
真正难的不是写对一行代码，而是理解 Iris 的 ctx 只活在一个 goroutine 里、只管一次 HTTP 请求、不自动蔓延——所有“共享”都得靠人一处处显式搬运。漏掉任意一环，链路就断在那。
