以下是基于 Gin 框架的典型企业级项目结构设计(分层架构),包含模块化、可测试性和扩展性考量:
├── cmd
│ └── app
│ └── main.go # 入口文件
├── config # 配置管理
│ ├── config.go # 配置结构定义
│ └── local.yml # 配置文件
├── internal # 内部代码(禁止外部引用)
│ ├── controllers # HTTP 控制器
│ ├── middlewares # 中间件
│ ├── models # 数据模型
│ ├── repositories # 数据持久层
│ ├── services # 业务逻辑层
│ ├── routes # 路由定义
│ ├── pkg # 内部共享包
│ │ ├── cache # 缓存实现
│ │ ├── database # 数据库连接
│ │ ├── logger # 日志处理
│ │ └── validator # 参数验证
│ └── utils # 工具函数
├── api
│ └── swagger # OpenAPI 文档
├── test # 集成测试
├── scripts # 部署/运维脚本
├── deployments # Docker/K8s 配置
├── web # 前端静态资源(可选)
├── go.mod
├── go.sum
└── README.md
核心分层架构说明
- HTTP 层 (Controllers)
职责:处理 HTTP 请求/响应
最佳实践:
// 示例Controller type UserController struct { userService services.UserService } func (c *UserController) GetUser(ctx *gin.Context) { id := ctx.Param("id") user, err := c.userService.GetByID(id) // 统一处理响应... }
- 业务逻辑层 (Services)
- 职责:实现核心业务逻辑
- 示例接口:
type UserService interface { Create(user models.User) error GetByID(id string) (*models.User, error) Update(user models.User) error }
- 数据持久层 (Repositories)
职责:与数据库交互
示例实现:
type userRepository struct { db *gorm.DB } func (r *userRepository) FindByID(id string) (*models.User, error) { var user models.User result := r.db.First(&user, "id = ?", id) return &user, result.Error }
关键组件集成
- 配置管理
// 使用 viper 读取配置
func InitConfig() {
viper.SetConfigFile("config/local.yml")
if err := viper.ReadInConfig(); err != nil {
log.Fatal("Failed to read config file")
}
}
- 统一响应处理
func ResponseJSON(ctx *gin.Context, code int, data interface{}) {
ctx.JSON(code, gin.H{
"code": code,
"data": data,
"msg": "success",
})
}
- 中间件示例 (JWT 验证)
func JwtAuth() gin.HandlerFunc {
return func(c *gin.Context) {
tokenString := c.GetHeader("Authorization")
// 验证逻辑...
c.Next()
}
}
进阶实践建议
- 依赖管理
- 使用依赖注入(推荐使用 Wire):
func InitializeUserController(db *gorm.DB) *controllers.UserController { userRepo := repositories.NewUserRepository(db) userService := services.NewUserService(userRepo) return controllers.NewUserController(userService) }
- 错误处理
创建自定义错误类型:
type AppError struct { Code int Message string } func (e *AppError) Error() string { return e.Message }
- 测试策略
- 单元测试服务层:
func TestUserService_Create(t *testing.T) { mockRepo := new(MockUserRepository) service := services.NewUserService(mockRepo) // 设置mock预期... }
- 性能优化
使用 pprof 分析性能:
import _ "net/http/pprof" go func() { http.ListenAndServe(":6060", nil) }()
- 安全增强
- 配置 CORS 中间件:
config := cors.DefaultConfig() config.AllowOrigins = []string{"https://example.com"} router.Use(cors.New(config))
推荐工具链
- 数据库:GORM + pgx/mysql 驱动
- 配置管理:Viper
- 日志记录:Zap + Logrus
- 文档生成:Swagger (go-swagger)
- 测试框架:Testify + Mockery
- CI/CD:GitHub Actions / GitLab CI
项目初始化示例
func main() {
// 初始化配置
config.In
最近更新