上下文键

xCtx 包定义了用于在上下文中存储和获取数据的键常量。

import xCtx "github.com/bamboo-services/bamboo-base-go/defined/context"

ContextKey 类型

context.go

type ContextKey string

func (s ContextKey) String() string {
    return string(s)
}

预定义键

context.go

const (
    Nil              ContextKey = ""                        // 空值
    Exec             ContextKey = "special_execution"       // 特殊执行
    RegNodeKey       ContextKey = "context_reg_node"        // 注册节点
    RequestKey       ContextKey = "context_request_key"     // 请求唯一标识
    ErrorCodeKey     ContextKey = "context_error_code"      // 错误码
    ErrorMessageKey  ContextKey = "context_error_message"   // 错误描述
    UserStartTimeKey ContextKey = "context_user_start_time" // 请求开始时间
    DatabaseKey      ContextKey = "context_database"        // 数据库客户端
    RedisClientKey   ContextKey = "context_redis_client"    // Redis 客户端
    CacheManagerKey  ContextKey = "context_cache_manager"   // 缓存管理器
    SnowflakeNodeKey ContextKey = "context_snowflake_node"  // 雪花算法节点
)

键说明

字段

类型

使用方式

节点化注入（推荐）

在 Register 时通过节点注入资源：

import (
    "context"
    xCtx "github.com/bamboo-services/bamboo-base-go/defined/context"
    xReg "github.com/bamboo-services/bamboo-base-go/major/register"
    xRegNode "github.com/bamboo-services/bamboo-base-go/major/register/node"
)

// v1.0.5 起：通过 opts 声明式装配，框架自动注册保留键
reg := xReg.Register(context.Background(), nil,
    xOption.WithDatabase(xOptDatabase.FromEnv()),  // → DatabaseKey（v1.2.0 起需导入对应驱动插件）
    xOption.WithCache(xOptCache.FromEnv()),        // → CacheManagerKey + RedisClientKey
)
// SnowflakeNodeKey / DatabaseKey / CacheManagerKey / RedisClientKey
// 均为框架保留键，不能在 nodeList 中重复注册

从上下文获取值

使用 xCtxUtil 工具函数获取注入的资源：

import xCtxUtil "github.com/bamboo-services/bamboo-base-go/common/utility/context"

func MyHandler(c *gin.Context) {
    // 获取标准上下文
    ctx := c.Request.Context()

    // 获取数据库连接
    db := xCtxUtil.MustGetDB(ctx)

    // 获取 Redis 客户端
    rdb := xCtxUtil.MustGetRDB(ctx)

    // 获取雪花算法节点
    node := xCtxUtil.GetSnowflakeNode(ctx)
}

直接从上下文获取

也可以直接使用 context.Value 获取：

import xCtx "github.com/bamboo-services/bamboo-base-go/defined/context"

func MyHandler(c *gin.Context) {
    ctx := c.Request.Context()

    // 直接获取并类型断言
    if value := ctx.Value(xCtx.DatabaseKey); value != nil {
        db := value.(*gorm.DB)
    }
}

注入时机

键	注入位置	说明
`RequestKey`	`xHelper.RequestContext()`	框架自动注入
`UserStartTimeKey`	`xHelper.RequestContext()`	框架自动注入
`SnowflakeNodeKey`	`xReg.Register()` 内置节点	框架自动注入
`DatabaseKey`	`xReg.Register()` 根据 `opts`	v1.0.5 起框架保留键，启用 `WithDatabase` 时自动注入
`CacheManagerKey`	`xReg.Register()` 根据 `opts`	v1.0.5 起框架保留键，启用 `WithCache` 时自动注入
`RedisClientKey`	`xReg.Register()` 根据 `opts`	v1.0.5 起框架保留键，Redis 后端时自动注入
`ErrorCodeKey`	错误处理中间件	错误时自动设置
`ErrorMessageKey`	错误处理中间件	错误时自动设置

框架保留键（v1.0.5）：SnowflakeNodeKey / DatabaseKey / CacheManagerKey / RedisClientKey 由 Register 根据 opts 自动注册，不得出现在 nodeList 中，否则 Use 会因重复注册 panic。

上下文流转

Register(ctx, nodeList, opts...)
    │
    ├── 框架保留键：SnowflakeNodeKey（始终）
    ├── 框架保留键：DatabaseKey（opts 含 WithDatabase 时）
    ├── 框架保留键：CacheManagerKey + RedisClientKey（opts 含 WithCache 时）
    ├── 业务自定义节点（来自 nodeList，键不得与保留键冲突）
    │
    └── engineInit()
            │
            └── injectContext(ctx) 中间件
                    │
                    └── 每个 HTTP 请求
                            │
                            └── c.Request.Context() 包含所有注入的资源

上下文键

上下文键

ContextKey 类型

预定义键

键说明

使用方式

节点化注入（推荐）

从上下文获取值

直接从上下文获取

注入时机

上下文流转

下一步

工具函数

概述

On this page