Fiber项目模块化关键在于严守分层边界:handler→service→repository→model单向依赖,model必须纯struct零方法零框架感知,否则必现import cycle、HTTP上下文泄漏等崩坏问题。

Fiber 项目不能靠“建 controller/service/model 目录”就叫模块化,真这么干,两周后就会遇到 import cycle not allowed、c.JSON 泄露到 repository、service 里写 db.Create 硬编码等典型崩坏现场。
fiber.New() 之后别急着写路由,先划清层间边界
Handler 层唯一合法依赖是 service 接口;service 层只调用 repository 接口;repository 层只操作 model 结构体 + 数据库驱动(如 *gorm.DB 或 *sql.DB);model 层必须是纯 struct,零方法、零 import、零 tag 以外的逻辑。
常见错误现象:
-
user_service.go里直接 newuser_repo.UserRepo{db: globalDB}→ 无法测试、无法替换实现 -
user_model.go定义func (u *User) Save(ctx *fiber.Ctx) error→ 模型污染 HTTP 上下文 - 所有 handler 都从
config.Load()读配置 → 配置解析逻辑散落各处,启动时才发现缺失字段
正确做法是:在 main.go 统一构造依赖链,用结构体字段注入:
type App struct {
UserHandler *user_handler.Handler
UserService *user_service.Service
UserRepo *user_repo.Repo
DB *gorm.DB
}
func main() {
db := setupDB()
repo := user_repo.New(db)
svc := user_service.New(repo)
handler := user_handler.New(svc)
app := fiber.New()
app.Post("/users", handler.Create)
}
路由分组不是“模拟 Controller 类”,而是按业务域隔离
fiber.Group() 的本质是路径前缀 + 中间件组合,不是面向对象里的类封装。滥用它塞一堆闭包,会导致中间件执行顺序难追溯、错误日志定位困难、权限校验逻辑被重复粘贴。
使用场景:
- 按业务域拆分:比如
/api/v1/users和/api/v1/orders各自独立 group,不共享 handler 或中间件 - 按权限级别隔离:比如
/admingroup 显式挂载auth.AdminOnly(),而非在每个 handler 里if !c.Locals("role")... - 避免嵌套过深:group 嵌套超过两层(如
app.Group("/v1").Group("/admin").Group("/users"))会显著增加路由调试成本
参数差异注意点:
-
app.Group("/api", middleware...)中的 middleware 是「进入该前缀的所有请求都走」,不是条件触发 - group 内部注册的
.Get/.Post路径是相对路径,app.Group("/v1").Get("/users")实际匹配/v1/users,不是/users
service 层必须接收已校验输入,拒绝裸指针和上下文穿透
handler 解析参数后,应完成基础校验(非空、长度、格式),再传给 service。service 层绝不该再做 c.Params 或 c.Query,更不能接收 *fiber.Ctx。
容易踩的坑:
- 定义
func CreateUser(c *fiber.Ctx) error在 service → 违反单向依赖,且无法单元测试 - service 方法签名是
func (s *Service) Create(u *model.User) error→ 允许传入 nil 指针,panic 风险高 - 用
map[string]interface{}当参数 → 类型丢失,IDE 无提示,重构易出错
推荐写法:
// 定义明确的输入结构体(放在 service 包内或单独 req/ 目录)
type CreateUserReq struct {
Name string `json:"name" validate:"required,min=2"`
Email string `json:"email" validate:"required,email"`
}
// service 方法只认这个结构体
func (s *Service) Create(req CreateUserReq) (model.User, error) {
// 业务规则检查,比如邮箱是否已存在
if s.repo.ExistsByEmail(req.Email) {
return model.User{}, errors.New("email exists")
}
// 构造 model 并保存
u := model.User{Name: req.Name, Email: req.Email}
if err := s.repo.Create(&u); err != nil {
return model.User{}, err
}
return u, nil
}
model 层禁止任何框架感知,包括 JSON tag 之外的修饰
model 不是 ORM 实体,也不是 DTO,它只是数据载体。GORM tag 可以有(gorm:"primaryKey"),但 fiber.Ctx、echo.Context、binding:"required" 这类框架专属内容必须零出现。
为什么这点容易被忽略:
- 为了省事,在
model.User上加json:"-" gorm:"-" binding:"required"→ binding 是 validator 库的,不属于 model 职责 - 把 API 响应结构体(如
UserResp)和数据库模型(User)混在一个文件里 → 字段增减时互相干扰 - 在 model 里写
func (u *User) ToResp() UserResp→ model 开始承担转换逻辑,违反单一职责
正确组织方式:
- model/ 下只放
type User struct { ID int `json:"id" gorm:"primaryKey"` } - request/response 结构体放在
internal/req/和internal/resp/,与 handler 或 service 同级 - 转换逻辑收口在 handler 里,比如
c.JSON(resp.FromModel(user)),不放进 model
真正卡住多数人的不是 Fiber 语法,而是没守住 model 层的“哑性”——一旦它开始调用数据库、响应客户端、校验参数,整个分层就塌了。边界感比代码量重要得多。











