GoFrame项目必须严格遵循api、internal、manifest三层核心目录结构:api只定义数据契约,internal封闭实现业务闭环(含controller/service/dao等子层),manifest统一管理运行时配置。

要让GoFrame项目具备可维护性、可协作性和可交付性,必须严格遵循其约定的分层结构,不能把所有代码堆在main.go里或随意新建目录。分层不是为了形式主义,而是为了让controller只管请求流转、service只管业务规则、dao只管数据存取——改一个字段名不会波及三个文件夹。
理解三层核心目录的边界
GoFrame项目中真正承载业务逻辑的只有三个顶层目录:api、internal、manifest。其他如resource、utility、hack等属于辅助角色,不参与主干链路。
api目录存放的是纯数据契约,不包含任何逻辑;internal是整个业务实现的封闭黑盒,外部无法直接引用其子包;manifest是运行时的“决策中心”,它决定程序启动时加载哪些配置、监听哪个端口、启用什么中间件。
【internal目录下所有子包均被Go语言internal机制强制限制对外不可见】,这意味着你无法从另一个模块import internal/controller,这天然防止了跨层调用混乱。
api目录:只定义,不实现
api目录本质是一份接口协议说明书,它用Go结构体声明输入参数(如LoginReq)、输出结果(如LoginRes)和错误码枚举(如CodeUserNotFound)。
典型路径为api/v1/user.go,其中v1表示版本号,支持多版本并存;user.go里只放LoginReq、LoginRes、UserListRes等结构体,以及可能的校验规则tag(如`json:"username" validate:"required|length:3,20"`)。
这个目录不写一行业务逻辑,不调用任何service或dao,也不依赖ghttp、gdb等框架组件。它的唯一职责就是被controller引用做参数绑定和响应序列化。
internal目录:业务逻辑的完整闭环
internal是GoFrame项目真正的“心脏”,它又被细分为controller、service、dao、model、consts、cmd等子目录,每个子目录有明确且不可逾越的职责边界。
第一步:controller接收请求→解析参数→调用service→组装响应→返回结果。它不做任何业务判断,只做流程调度。
第二步:service实现具体业务规则。比如用户注册时,需检查用户名是否重复、密码是否符合强度、是否发送欢迎邮件——这些逻辑全在service层,且每个方法应单一职责,例如RegisterUserService.Register()只负责注册主干,校验交给ValidateUserService,发邮件交给NotifyService。
第三步:dao负责与数据库对话。它只生成SQL、执行Query/Insert/Update/Delete,不处理任何业务含义。DAO代码应由gf gen dao命令自动生成,禁止手写SQL拼接。
model目录下entity子目录存放与数据库表一一对应的实体结构(如UserEntity),do子目录存放DAO操作所需的数据对象(如UserDo),二者均由工具生成,【手动修改do或entity会导致后续gen命令覆盖丢失】。
manifest目录:运行时的配置总控台
manifest目录存放config.yaml、routes.yaml、middleware.yaml等YAML文件,它们共同构成程序启动前的配置快照。
config.yaml定义数据库连接地址、Redis配置、JWT密钥、日志级别等环境相关参数;routes.yaml声明路由与controller方法的映射关系(替代硬编码BindHandler);middleware.yaml控制CORS、鉴权、限流等中间件的启用开关和顺序。
这些文件在gf run启动时被自动加载,无需在代码中显式读取。修改后重启即可生效,避免把配置散落在几十个go文件里。
manifest不是静态资源目录,也不是部署脚本存放地——它只承载影响程序行为的运行时参数,其它如Dockerfile、k8s yaml应放在项目根目录或单独infra仓库中。
大量免费API接口:立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游,为数据API应用能力赋能!











