介绍

简介

go-web 是 木雷坞(mliev) 开源的企业级 Go Web 应用模板。它在 Gin 之上提供了一整套约定与抽象,目标是让团队在新项目里跳过基础设施搭建、直接进入业务开发。

模块路径:cnb.cool/mliev/open/go-web,要求 Go 1.25.0 及以上版本。

核心特性

• 清晰的分层架构 —— Controller → Service → DAO → Model,各层职责单一
• 依赖注入容器 —— 懒加载单例、按类型查找、优先级覆盖、反射注入,运行时检测循环依赖
• 可插拔驱动系统 —— 数据库 / 日志 / 缓存 / Redis / 静态资源 均可在配置中按名称切换实现
• 多数据库支持 —— 内置 mysql / postgresql / sqlite / memory 四种驱动
• 版本化数据库迁移 —— 基于 Goose,支持 up / down / status / create / redo,服务启动时自动 Up
• 结构化日志 —— 基于 Zap,提供 development / production 两套预设
• 健康检查 —— GET /health 与 GET /health/simple 内置即用
• 配置管理 —— Viper 读取 config.yaml + 环境变量,所有键支持 _ 替代 . 的环境变量覆盖
• 优雅启停 —— SIGINT / SIGTERM 优雅关闭,SIGHUP 触发热重载(容器重置 + 重新装配)
• 框架无关控制器 —— Handler 接受 RouterContextInterface 而非 *gin.Context,屏蔽底层框架细节
• 正则路由 —— 在 Gin 标准路由之外提供基于正则表达式与命名捕获组的高级路由模式
• Functional Options 启动 —— 通过 cmd.Start(cmd.WithApp(...), cmd.WithTemplateFs(...), ...) 自定义入口
• 进程管理 —— 通过 gomander 提供 start / stop / restart / reload / status 子命令

适合谁

• 需要快速搭建一个生产级 Go Web 服务,但不想从零拼装 Gin + GORM + Viper + Zap 的团队
• 已有 PHP/Laravel、Java/Spring 背景,希望沿用「容器 + Provider + 装配链」心智模型的开发者
• 想要在多个项目间复用同一套基础设施代码,并通过 driver 切换具体实现的小型团队

与 Gin 的关系

go-web 不是 Gin 的替代品,而是基于 Gin 之上的应用骨架。底层 HTTP 仍由 Gin 提供,但应用代码只面向 RouterContextInterface、HandlerFunc 等接口编写。这样做的好处:

• 控制器单元测试无需构造 *gin.Context
• 未来如果替换底层框架,只需重新实现 pkg/server/http_server 内的适配器
• 中间件、上下文 API、错误响应等行为保持框架自有的一致风格

下一步

• 阅读「快速开始」按 5 步把一个 Demo 跑起来
• 阅读「项目结构」了解每个目录的职责
• 阅读「依赖注入容器」了解贯穿全局的核心机制