GoFrame 框架开发最佳实践

提供 GoFrame 框架的官方最佳实践指导，包括项目结构、分层架构、配置管理、数据校验、数据库操作、中间件开发等开发规范。

触发条件

当用户询问以下问题时，此 Skill 会被触发：

go-frame 最佳实践
go-frame 开发规范
go-frame 项目结构
go-frame 分层架构
go-frame 路由注册
go-frame 数据库操作
go-frame 事务处理
go-frame 配置管理
go-frame 中间件
go-frame API 文档
go-frame 校验参数

核心内容

此 Skill 提供 GoFrame 框架开发的核心指导原则。详细内容包括项目目录结构、分层架构设计、配置管理、数据校验、数据库 CRUD 操作、事务处理、中间件开发、日志管理、API 文档生成等。

项目目录结构

GoFrame 官方推荐的标准目录结构如下：

├── api                  # API 接口定义层
│   └── user             # 按模块划分
│       └── v1           # 版本号
│           └── user.go  # 接口定义文件
├── internal
│   ├── cmd              # 命令行启动入口
│   │   └── cmd.go       # 服务启动命令
│   ├── controller       # 控制器层（请求接收）
│   │   └── user         # 按模块划分
│   │       └── user.go
│   ├── logic            # 业务逻辑层（核心）
│   │   └── user
│   │       └── user.go
│   ├── model            # 数据模型层
│   │   ├── entity.go    # 数据库实体
│   │   └── do.go        # 数据对象
│   └── service          # 服务层
├── manifest             # 部署配置
│   ├── config           # 配置文件
│   └── docker           # Docker 配置
├── go.mod
└── main.go

关键原则：

internal 目录下的包只能被本项目导入，确保内部逻辑不对外暴露
使用 api 定义接口契约，internal 实现具体逻辑
cmd 目录下管理服务启动命令

分层架构设计

GoFrame 采用经典的三层（或四层）架构设计：

Controller 层：负责接收请求、参数校验，调用 Logic 层处理业务逻辑。Controller 层保持轻量，只做请求转发，使用依赖注入方式注入 Logic 层。
Logic 层：是核心业务处理单元，负责具体的业务规则实现。事务处理在 Logic 层进行，保持 Controller 和 Logic 的单向依赖。
Model 层：定义数据结构，包括实体和数据传输对象。使用 dc: tag 添加字段描述用于 API 文档。

配置管理

GoFrame 使用 g.Cfg() 单例管理配置，支持多种配置文件格式（toml/yaml/yml/json/ini/xml/properties）。配置项支持层级访问（使用 . 分隔）。

数据校验

使用 v:"规则#错误信息" 格式定义校验规则，使用 p: tag 定义参数名，使用 dc: tag 添加字段描述。使用 g.Validator() 进行参数校验。

数据库操作

基础 CRUD 操作使用 g.DB().Model() 方法，事务处理使用 Transaction() 或 TransactionWithOptions() 方法。根据业务场景选择合适的隔离级别。

中间件开发

中间件使用 r.Middleware.Next() 执行后续逻辑，错误处理中间件放在最后。遵循职责单一原则。

API 文档生成

使用 s.SetOpenApiPath() 和 s.SetSwaggerPath() 启用 Swagger 文档。使用 g.Meta 定义接口元信息，使用 dc: tag 描述字段含义。

参考资源

详细内容和代码示例请参考以下文件：

references/project-structure.md - 项目目录结构详解
references/layered-architecture.md - 分层架构设计模式
references/configuration.md - 配置管理最佳实践
references/database.md - 数据库操作和事务处理
references/middleware.md - 中间件开发指南
examples/controller-example.go - Controller 层示例代码
examples/logic-example.go - Logic 层示例代码
examples/middleware-example.go - 中间件示例代码

常用命令

命令	说明
`gf run main.go`	快速运行项目
`gf gen ctrl`	生成 Controller
`gf gen service`	生成 Service
`gf gen pb`	生成 Protobuf 文件

go-frame-best-practices