xReg 包

xReg 包是 Bamboo Base 的核心注册模块，采用节点化模式实现灵活的组件初始化和依赖注入。

import xReg "github.com/bamboo-services/bamboo-base-go/major/register"
import xRegNode "github.com/bamboo-services/bamboo-base-go/major/register/node"

Reg 结构体

应用程序的核心注册结构，包含所有初始化后的组件实例：

type Reg struct {
    Serve *gin.Engine       // Gin 引擎实例
    Init  *xRegNode.RegNode // 初始化节点管理器
}

字段

类型

Register

注册并初始化应用的所有核心组件，支持自定义初始化节点。

func Register(ctx context.Context, nodeList []xRegNode.RegNodeList, opts ...xOption.Option) *Reg

参数说明：

字段

类型

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

初始化顺序：

Register(ctx, nodeList, opts...)
    ├── configInit()           // 1. 加载 .env 配置（私有）
    ├── loggerInit()           // 2. 初始化日志（私有）
    ├── SnowflakeInit          // 3. 基础设施：雪花算法节点（框架注册）
    ├── DatabaseInit           // 4. 基础设施：数据库（来自 opts，启用时）
    ├── CacheInit              // 5. 基础设施：缓存（来自 opts，启用时）
    │   └── RedisClientFromManager  // 5.1 Redis 后端补注册 *redis.Client
    ├── [自定义节点...]         // 6. 业务自定义节点（来自 nodeList）
    ├── Init.Exec()            // 7. 一次性执行全部装配
    ├── engineInit()           // 8. 初始化 Gin 引擎（私有）
    └── 路由注册                // 9. 按 opts.Routes() 顺序挂载路由

启动阶段（推荐）
    └── xMain.Runner(...)      // 10. 启动 HTTP 服务并托管优雅关闭

示例：

main.go

package main

import (
    "context"

    xCtx "github.com/bamboo-services/bamboo-base-go/defined/context"
    xLog "github.com/bamboo-services/bamboo-base-go/common/log"
    xMain "github.com/bamboo-services/bamboo-base-go/major/main"
    xOption "github.com/bamboo-services/bamboo-base-go/major/option"
    xOptDatabase "github.com/bamboo-services/bamboo-base-go/major/option/database"
    xReg "github.com/bamboo-services/bamboo-base-go/major/register"
    xRegNode "github.com/bamboo-services/bamboo-base-go/major/register/node"

    // v1.2.0 起驱动插件化：按 DATABASE_DRIVER 空白导入对应驱动插件（此处以 mysql 为例）
    _ "github.com/bamboo-services/bamboo-base-go/plugins/database/mysql"

    "github.com/gin-gonic/gin"
)

func main() {
    // v1.0.5 起：opts 直接传给 Register，统一装配内置组件
    // 业务自定义节点列表只放纯业务逻辑，不再手写数据库初始化
    reg := xReg.Register(context.Background(),
        []xRegNode.RegNodeList{
            {Key: xCtx.CustomClientKey, Node: initCustomSDK},
        },
        xOption.WithDatabase(xOptDatabase.FromEnv()), // 从环境变量装配数据库（v1.2.0 起需导入对应驱动插件）
        xOption.WithRoute(func(ctx context.Context, serve *gin.Engine) {
            serve.GET("/ping", func(c *gin.Context) {
                c.String(http.StatusOK, "pong")
            })
        }),
    )

    log := xLog.WithName(xLog.NamedMAIN)
    xMain.Runner(reg, log, nil)
}

// 自定义初始化节点（业务 SDK / 第三方组件）
func initCustomSDK(ctx context.Context) (any, error) {
    // 可直接从 ctx 取 *gorm.DB / *xCache.Manager（已由 opts 装配）
    db := ctx.Value(xCtx.DatabaseKey).(*gorm.DB)
    // ...
    return sdk, nil
}

节点化系统

RegNode 结构

// Node 定义初始化函数签名
type Node func(ctx context.Context) (any, error)

// RegNodeList 存储节点信息
type RegNodeList struct {
    Key  xCtx.ContextKey  // 上下文键
    Node Node                // 初始化函数
}

// RegNode 节点管理器
type RegNode struct {
    list []RegNodeList
    Ctx  context.Context
}

核心方法

// Use 注册初始化节点
func (rn *RegNode) Use(ctxKey xCtx.ContextKey, registerFunc Node)

// Exec 按顺序执行所有节点
func (rn *RegNode) Exec()

执行流程

func (rn *RegNode) Exec() {
    for i, node := range rn.list {
        // 执行节点初始化
        val, err := node.Node(rn.Ctx)
        if err != nil {
            panic(fmt.Sprintf("执行注册节点失败: index=%d Key=%v err=%v", i, node.Key, err))
        }
        // 将结果存入上下文，供后续节点使用
        rn.Ctx = context.WithValue(rn.Ctx, node.Key, val)
    }
    rn.list = nil // 释放内存
}

特点：

🔄 依赖注入：每个节点可访问前面节点的初始化结果
📊 顺序执行：按注册顺序依次初始化
🛡️ 错误处理：任何节点失败都会 panic 并输出详细信息

内置初始化

配置初始化（私有）

从 .env 文件加载环境变量配置。

详见：配置初始化

日志初始化（私有）

初始化日志记录器，支持控制台彩色输出和文件 JSON 记录。

详见：日志初始化

雪花算法节点（内置）

作为内置节点自动注册，初始化雪花算法节点。

reg.Init.Use(xCtx.SnowflakeNodeKey, xInit.SnowflakeInit)

详见：雪花算法初始化

引擎初始化（私有）

初始化 Gin 引擎，注册内置中间件和验证器，并注入初始化上下文。

详见：引擎初始化

服务运行时（公共）

推荐使用 xMain.Runner 启动服务，统一处理：

信号监听（SIGINT/SIGTERM）
优雅关闭
后台协程托管

详见：服务运行时

gRPC 为可选能力，已拆分到独立板块：gRPC（可选）

上下文注入

引擎初始化时会自动将节点管理器的上下文注入到每个 HTTP 请求：

register_gin.go

// 注入初始化上下文到每个请求
func injectContext(ctx context.Context) func(c *gin.Context) {
    return func(c *gin.Context) {
        c.Request = c.Request.WithContext(ctx)
        c.Next()
    }
}

这意味着在业务代码中可以通过 c.Request.Context() 获取初始化时注入的所有资源。

调试模式

通过环境变量 XLF_DEBUG 控制调试模式：

环境变量	值	效果
`XLF_DEBUG`	`true`	启用调试模式，日志级别为 Debug
`XLF_DEBUG`	`false` 或未设置	生产模式，日志级别为 Info

完整示例