核心说明
Bamboo Base 整体架构设计与模块说明
核心架构
项目概述
模块名称: github.com/bamboo-services/bamboo-base-go
Go 版本: 1.24+
项目定位: 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)
│ ├── helper/ # 核心中间件 (xHelper)
│ ├── hook/ # 钩子函数 (xHook)
│ ├── http/ # HTTP 常量 (xHttp)
│ ├── main/ # 服务运行时 (xMain)
│ ├── middleware/ # 业务中间件 (xMiddle)
│ ├── models/ # 数据模型基类 (xModels)
│ ├── register/ # 应用注册和初始化 (xReg)
│ ├── result/ # 响应结果处理 (xResult)
│ └── route/ # 路由处理 (xRoute)
│
└── plugins/ # 🔌 插件层 — 可选扩展
└── grpc/ # gRPC 支持
├── constant/ # gRPC 常量
├── generate/ # Proto 生成辅助
├── interceptor/ # 拦截器
├── middleware/ # gRPC 中间件
├── result/ # gRPC 响应处理
└── runner/ # gRPC 运行时包导入别名
defined 层（零依赖）
字段
类型
common 层（基础设施）
字段
类型
major 层（主框架）
字段
类型
plugins 层（可选扩展）
字段
类型
模块依赖关系
初始化流程
package main
import (
"context"
xReg "github.com/bamboo-services/bamboo-base-go/major/register"
)
func main() {
// 一键初始化所有组件
reg := xReg.Register(context.Background(), nil)
// 注册路由...
reg.Serve.Run(":8080")
}核心依赖
| 依赖 | 版本 | 用途 |
|---|---|---|
gin-gonic/gin | v1.10+ | Web 框架 |
go-playground/validator | v10.30+ | 验证器 |
joho/godotenv | v1.5+ | 环境变量加载 |
redis/go-redis | v9.14+ | Redis 客户端 |
gorm.io/gorm | v1.30+ | ORM 框架 |
设计原则
- 分层解耦 - 四层架构（defined → common → major → plugins），按需引入
- 单一职责 - 每个包只负责特定的功能领域
- 统一命名 - 所有包使用
x前缀别名，便于识别 - 约定优于配置 - 提供合理的默认值，减少配置负担
- 链路追踪 - 请求 ID 贯穿整个请求生命周期