必须从HTTP入口逐层透传ctx:Controller中用r.Context()获取并WithValue注入业务数据;Service/Repository函数签名需含ctx参数且调用DAO时显式.Ctx(ctx);异步任务应使用WithCancel派生子ctx或gproc.GoCtx;DAO操作须通过.Ctx(ctx)、模型Init或g.DB().Ctx(ctx)启用上下文。

要在GoFrame项目中确保请求链路中每个环节都能访问到统一的上下文信息,必须让ctx从HTTP入口开始逐层透传,不能在任意一层丢失或重新创建。
HTTP Handler入口处获取并初始化ctx
在Controller方法中,直接从*ghttp.Request对象中提取原始ctx:ctx := r.Context()。这一步不可跳过,也不能用context.Background()替代,否则链路跟踪ID、超时控制、日志关联等能力全部失效。
如果需要注入业务共享变量(如用户登录态),应立即用context.WithValue包装:ctx = context.WithValue(ctx, model.ContextKey, &model.Context{User: user})。注意:键名model.ContextKey必须全局唯一且类型一致,否则下游无法正确取出。
Service与Repository层必须显式接收并传递ctx
所有中间层函数签名都必须包含ctx context.Context参数,例如:func (s *UserService) GetUser(ctx context.Context, id int) (*User, error)。
调用下游方法时,必须把当前ctx原样传入,不能省略或替换为新上下文。比如在Service中调用DAO时写成:user, err := dao.User.Ctx(ctx).Where("id", id).One()——这里Ctx(ctx)是关键,ORM才真正将链路信息注入SQL执行上下文。
【不传递ctx会导致数据库操作脱离链路追踪,日志中无TraceID,超时控制完全失效】
跨协程或异步任务中安全延续ctx
方法一:使用context.WithCancel派生子上下文
当启动goroutine处理耗时子任务(如发消息、写日志)时,应基于当前请求ctx派生:childCtx, cancel := context.WithCancel(ctx),并在goroutine结束前调用cancel()。这样父ctx取消时,子任务也会收到信号退出。
方法二:避免在goroutine中直接使用原始ctx
不要写go func() { db.QueryContext(ctx, ...) }()这种代码。因为ctx可能在goroutine执行前就已取消,QueryContext会立即返回错误;更糟的是,若ctx携带了用户信息等Value,异步执行时该Value可能已被GC回收或覆盖。
方法三:用gproc.GoCtx封装(GoFrame特有)
框架提供gproc.GoCtx(ctx, func(ctx context.Context) { ... }),自动绑定生命周期,推荐用于简单异步场景。
DAO与模型操作中启用ctx的三种方式
第一步:调用Ctx(ctx)方法显式绑定dao.User.Ctx(ctx).Where("status", 1).All()——这是最常用也最明确的方式,适用于所有链式查询。
第二步:在模型结构体中嵌入g.Model并重写Init方法
若使用自动生成的DAO模型,可在init函数中设置默认ctx行为,但需谨慎:全局默认ctx会掩盖具体请求上下文差异,调试困难。
第三步:通过g.DB().Ctx(ctx)获取带上下文的DB实例
适用于需要绕过DAO直接执行原生SQL的场景,例如:g.DB().Ctx(ctx).Query("UPDATE user SET updated_at=? WHERE id=?", time.Now(), id)。











