核心架构

项目概述

模块名称: github.com/bamboo-services/bamboo-base-go

Go 版本: 1.25+

项目定位: Go 语言基础框架库，为 Bamboo 服务提供核心功能支持，包括日志、错误处理、雪花算法 ID 生成、验证器、中间件等基础设施。

包结构说明

github.com/bamboo-services/bamboo-base-go/
│
├── defined/                    # 🏷️ 定义层 — 零依赖的常量与类型
│   ├── context/                #   上下文键常量 (xCtx)
│   └── env/                    #   环境变量常量 (xEnv)
│
├── common/                     # 🧱 公共层 — 可独立使用的基础设施
│   ├── base_response.go        #   统一响应结构体 (xBase)
│   ├── error/                  #   错误码和错误处理 (xError)
│   ├── log/                    #   日志系统 (xLog)
│   ├── snowflake/              #   雪花算法 ID 生成 (xSnowflake)
│   ├── utility/                #   工具函数 (xUtil)
│   │   └── context/            #   上下文工具 (xCtxUtil)
│   └── validator/              #   验证器 (xVaild)
│
├── major/                      # 🚀 主框架层 — 依赖 Gin 的核心组件
│   ├── cache/                  #   泛型缓存系统 (xCache) — Redis / Memory 双后端
│   │   ├── driver/             #     缓存接口定义与类型
│   │   ├── redis/              #     Redis 后端实现
│   │   └── memory/             #     Memory 后端实现
│   ├── helper/                 #   核心中间件 (xHelper)
│   ├── hook/                   #   钩子函数 (xHook)
│   ├── main/                   #   服务运行时 (xMain)
│   ├── middleware/             #   业务中间件 (xMiddle)
│   ├── models/                 #   数据模型基类 (xModels)
│   ├── option/                 #   声明式配置 (xOption)
│   │   └── database/           #     数据库选项配置
│   ├── register/               #   应用注册和初始化 (xReg)
│   │   ├── init/               #     内置初始化节点
│   │   └── node/               #     节点管理器
│   ├── result/                 #   响应结果处理 (xResult)
│   ├── route/                  #   路由处理 (xRoute)
│   └── utility/                #   请求绑定与上下文提取 (xUtil)
│
└── plugins/                    # 🔌 插件层 — 可选扩展
    ├── grpc/                   #   gRPC 支持
    │   ├── constant/           #     gRPC 常量
    │   ├── generate/           #     Proto 生成辅助
    │   ├── interceptor/        #     拦截器
    │   ├── middleware/         #     gRPC 中间件
    │   ├── result/             #     gRPC 响应处理
    │   └── runner/             #     gRPC 运行时
    ├── async/                  #   异步任务执行 (xAsync)
    ├── cron/                   #   定时任务 (xCron)
    │   └── runner/             #     Cron 运行时
    └── email/                  #   邮件服务 (xEmail)

包导入别名

defined 层（零依赖）

字段

类型

common 层（基础设施）

字段

类型

major 层（主框架）

字段

类型

plugins 层（可选扩展）

字段

类型

模块依赖关系

初始化流程

main.go

package main

import (
    "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"

    // v1.2.0 起驱动插件化：按 DATABASE_DRIVER 空白导入对应驱动插件
    _ "github.com/bamboo-services/bamboo-base-go/plugins/database/mysql"
)

func main() {
    // 一键初始化所有组件，opts 声明式装配内置组件
    reg := xReg.Register(context.Background(), nil,
        xOption.WithDatabase(xOptDatabase.FromEnv()),
    )

    log := xLog.WithName(xLog.NamedMAIN)
    // 启动服务并优雅关闭
    xMain.Runner(reg, log, nil)
}

核心依赖

依赖	版本	用途
`gin-gonic/gin`	v1.12+	Web 框架
`go-playground/validator`	v10.30+	验证器
`joho/godotenv`	v1.5+	环境变量加载
`redis/go-redis`	v9.21+	Redis 客户端
`gorm.io/gorm`	v1.31+	ORM 框架
`plugins/database/mysql`	v1.2.0+	MySQL GORM 驱动插件
`plugins/database/postgres`	v1.2.0+	PostgreSQL GORM 驱动插件
`plugins/database/sqlite`	v1.2.0+	SQLite GORM 驱动插件（纯 Go）
`plugins/database/oracle`	v1.2.0+	Oracle GORM 驱动插件（依赖 godror + Instant Client）
`plugins/database/sqlserver`	v1.2.0+	SQL Server GORM 驱动插件
`wneessen/go-mail`	v0.6+	邮件发送
`robfig/cron/v3`	v3.0+	定时任务
`google.golang.org/grpc`	v1.82+	gRPC 框架

设计原则

分层解耦 - 四层架构（defined → common → major → plugins），按需引入
单一职责 - 每个包只负责特定的功能领域
统一命名 - 所有包使用 x 前缀别名，便于识别
约定优于配置 - 提供合理的默认值，减少配置负担
链路追踪 - 请求 ID 贯穿整个请求生命周期
后端可切换 - 缓存等组件支持 Redis / Memory 双后端，零代码切换

核心说明

核心架构

项目概述

包结构说明

包导入别名

defined 层（零依赖）

common 层（基础设施）

major 层（主框架）

plugins 层（可选扩展）

模块依赖关系

初始化流程

核心依赖

设计原则

下一步

节点初始化

响应处理

On this page