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) *Reg

参数说明：

字段

类型

初始化顺序：

Register(ctx, nodeList)
    ├── configInit()           // 1. 加载配置（私有）
    ├── loggerInit()           // 2. 初始化日志（私有）
    ├── SnowflakeInit          // 3. 内置雪花算法节点
    ├── [自定义节点...]         // 4. 用户自定义节点
    └── engineInit()           // 5. 初始化 Gin 引擎（私有）

启动阶段（推荐）
    └── xMain.Runner(...)      // 6. 启动 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"
    xReg "github.com/bamboo-services/bamboo-base-go/major/register"
    xRegNode "github.com/bamboo-services/bamboo-base-go/major/register/node"
    "github.com/gin-gonic/gin"
)

func main() {
    // 初始化，传入自定义节点
    reg := xReg.Register(context.Background(), []xRegNode.RegNodeList{
        {
            Key:  xCtx.DatabaseKey,
            Node: initDatabase,  // 自定义数据库初始化
        },
    })

    log := xLog.WithName(xLog.NamedMAIN)
    xMain.Runner(reg, log, func(reg *xReg.Reg) {
        reg.Serve.GET("/ping", func(c *gin.Context) {
            c.String(200, "pong")
        })
    })
}

// 自定义初始化节点
func initDatabase(ctx context.Context) (any, error) {
    // 从上下文获取配置（前面节点的结果）
    // 初始化数据库连接
    db, err := gorm.Open(...)
    return db, err
}

节点化系统

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

完整示例