This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Loading actions...
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Bamboo-Main 是一个基于 Gin + GORM 构建的友情链接管理系统，采用清洁架构设计。
bamboo-base-go，路径通过 replace 指向 /Users/xiaolfeng/ProgramProjects/Cooperate/bamboo-service/bamboo-base# 开发
go run main.go # 启动服务
go mod tidy # 安装依赖
# 构建与测试
go build -o bamboo-main # 编译二进制
go test ./... # 运行测试
go fmt ./... # 代码格式化
go vet ./... # 代码检查
# 文档
swag init -g main.go -o docs # 生成 Swagger 文档 (访问 /swagger/index.html)
Handler (internal/handler/) - HTTP 请求处理、参数校验、响应封装
↓
Logic (internal/logic/) - 业务逻辑编排、数据转换、规则校验
↓
Service (internal/service/) - 数据库/Redis 操作、数据访问封装
重要原则:
internal/
├── handler/ # HTTP 处理层
├── logic/ # 业务逻辑层
├── service/ # 数据访问层
├── middleware/ # 中间件 (认证、权限)
├── model/
│ ├── entity/ # 数据库实体 (对应表结构)
│ ├── dto/ # 数据传输对象 (API 响应)
│ └── request/ # 请求参数
└── router/ # 路由配置
pkg/
├── startup/ # 应用启动初始化
├── constants/ # 全局常量 (Redis Key、状态码等)
└── util/ # 工具函数
cs_ + 64位随机字符串bm:auth:token:{token}, TTL: 24小时middleware.AuthMiddleware() - 验证 Token 并注入用户上下文middleware.RequireRole("admin", "moderator") - 基于角色的访问控制上下文使用:
// 获取当前用户 UUID
userUUID := ctx.GetString(constants.ContextKeyUserUUID)
// 获取当前用户信息 (需先从 service 加载)
user, _ := xCtx.GetCurrentUser(ctx)
0-待审核, 1-已通过, 2-已拒绝is_failure (0-正常, 1-失效)GroupUUID (分组), ColorUUID (颜色)/api/v1/admin/groups/sort)group_uuid 会被置为 NULLbm_ (通过 database.prefix 配置)BeforeCreate/BeforeUpdate Hooks数据库迁移在启动时自动执行 (pkg/startup/register_database.go):
xDatabase.DB.AutoMigrate(
&entity.SystemUser{},
&entity.LinkFriend{},
&entity.LinkGroup{},
&entity.LinkColor{},
&entity.Log{},
&entity.SystemInfo{},
)
注意: 修改实体结构后,需重启服务以应用迁移。
前缀: bm (bamboo-main)
// 常量位置: pkg/constants/redis.go
bm:auth:token:{token} // Token 会话
bm:link:cache:{uuid} // 链接缓存
bm:group:list:{key} // 分组列表
bm:email:limit:{email} // 邮件频率限制
配置文件: configs/config.yaml
xlf:
debug: true # true=开发模式(启用Swagger), false=生产模式
server:
port: 23333
database: # PostgreSQL 配置
host: localhost
port: 5432
user: bamboo_main
pass: bamboo_main
name: bamboo_main
prefix: bm_
sslmode: disable
timezone: Asia/Shanghai
nosql: # Redis 配置
host: localhost
port: 6379
pass: ""
database: 0
prefix: "bm"
email: # 邮件配置 (TODO: 未实现)
smtp_host: smtp.gmail.com
smtp_port: 587
加载方式: pkg/startup/register_config.go → 解析为 model.BambooConfig → 注入上下文
internal/model/entity/xxx.gointernal/model/request/xxx_request.gointernal/model/dto/response/xxx_response.gointernal/service/xxx.go (数据访问)internal/logic/xxx.go (业务逻辑)internal/handler/xxx.go (HTTP 处理)internal/router/router_xxx.go// @Summary, // @Tags 等swag init -g main.go -o docs// AddLink godoc
// @Summary 添加友情链接
// @Description 管理员添加新的友情链接
// @Tags admin-links
// @Accept json
// @Produce json
// @Param request body request.LinkAddRequest true "添加友链请求"
// @Success 200 {object} result.Result
// @Failure 400 {object} result.Result
// @Router /api/v1/admin/links [post]
// @Security Bearer
func (h *LinkHandler) AddLink(ctx *gin.Context) {
var req request.LinkAddRequest
if err := ctx.ShouldBindJSON(&req); err != nil {
xResult.Error(ctx, xError.ParamError)
return
}
if err := logic.LinkLogic{}.Add(ctx, &req); err != nil {
xResult.Error(ctx, err)
return
}
xResult.Success(ctx, "添加成功", nil)
}
gofmt/goimports,制表符缩进重要：从 xCtxUtil.GetDB(ctx) 获取的 db 实例已包含 Snowflake 节点，不要再次调用 WithContext 覆盖！
❌ 错误：
db := xCtxUtil.GetDB(ctx)
err := db.WithContext(ctx.Request.Context()).Create(&user).Error // 会丢失 Snowflake 节点
✅ 正确：
db := xCtxUtil.GetDB(ctx)
err := db.Create(&user).Error // 直接使用即可
原理：
pkg/startup/register_database.go:85-88）已设置包含 Snowflake 节点的 contextWithContext() 会替换原有的 context，导致 BeforeCreate Hook 无法获取 Snowflake 节点生成主键 IDxCtxUtil.GetDB(ctx) 返回的 db 即可，无需额外设置 context遵循 Conventional Commits:
feat: 实现友链分组管理功能并重构网络工具包
refactor: 重构认证中间件并优化用户上下文管理
fix: 修复友链排序异常问题
chore: 更新依赖版本
*_test.goTestXxx这是本地共享基础库,提供通用功能:
// 初始化
xInit "github.com/bamboo-services/bamboo-base-go/init"
// 响应封装
xResult "github.com/bamboo-services/bamboo-base-go/result"
xResult.Success(ctx, "成功消息", data)
xResult.Error(ctx, xError.ParamError)
// 错误处理
xError "github.com/bamboo-services/bamboo-base-go/error"
xError.ParamError // 参数错误
xError.UnauthorizedError // 未授权
// 数据库
xDatabase "github.com/bamboo-services/bamboo-base-go/database"
xDatabase.DB.Model(&entity.LinkFriend{}).Find(&links)
// Redis
xRedis "github.com/bamboo-services/bamboo-base-go/nosql"
xRedis.Redis.Set(ctx, key, value, expiration)
// 上下文工具
xCtx "github.com/bamboo-services/bamboo-base-go/utility/ctx"
user, _ := xCtx.GetCurrentUser(ctx) // 获取当前登录用户
注意: 修改 bamboo-base-go 后,需在两个项目中同时运行 go mod tidy。
解决: 运行 swag init -g main.go -o docs 重新生成。
检查:
configs/config.yaml 中的数据库配置是否正确bamboo_main 是否已创建检查:
configs/config.yaml 中的 Redis 配置是否正确解决: 检查 go.mod 中的 replace 指令路径是否正确:
replace github.com/bamboo-services/bamboo-base-go v1.0.0-202508212147
=> /Users/xiaolfeng/ProgramProjects/Cooperate/bamboo-service/bamboo-base
adminadmin123456admin@example.com首次运行时自动创建 (pkg/startup/register_default_user.go)。
cs_ 前缀 + Redis 会话,24小时过期bm: 前缀,规范化命名