提供 GoFrame 框架的官方最佳实践指导，包括项目结构、分层架构、配置管理、数据校验、数据库操作、中间件开发等开发规范
提供 GoFrame 框架的官方最佳实践指导，包括项目结构、分层架构、配置管理、数据校验、数据库操作、中间件开发等开发规范。
当用户询问以下问题时，此 Skill 会被触发：
此 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() 执行后续逻辑，错误处理中间件放在最后。遵循职责单一原则。
使用 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 文件 |
